diff --git a/hipamd/README.md b/hipamd/README.md index 2361c75a12..309951ddb8 100644 --- a/hipamd/README.md +++ b/hipamd/README.md @@ -3,43 +3,44 @@ HIP allows developers to convert CUDA code to portable C++. The same source code can be compiled to run on NVIDIA or AMD GPUs. Key features include: -* HIP is very thin and has little or no performance impact over coding directly in CUDA or HCC "HC" mode. +* HIP is very thin and has little or no performance impact over coding directly in CUDA or hcc "HC" mode. * HIP allows coding in a single-source C++ programming language including features such as templates, C++11 lambdas, classes, namespaces, and more. * HIP allows developers to use the "best" development environment and tools on each target platform. * The "hipify" script automatically converts source from CUDA to HIP. -* Developers can specialize for the platform (CUDA or HCC) to tune for performance or handle tricky cases +* Developers can specialize for the platform (CUDA or hcc) to tune for performance or handle tricky cases -HIP is intended to support new developments in a portable C++ language that can run on either NVIDIA or AMD platforms. Additionally, HIP provides porting tools which make it easy to port existing CUDA codes to the portable HIP layer, with no loss of performance as compared to the original CUDA application. HIP is not intended to be a drop-in replacement for CUDA, and developers should expect to do some manual coding and performance tuning work to complete the port. +New projects can be developed directly in the portable HIP C++ language and can run on either NVIDIA or AMD platforms. Additionally, HIP provides porting tools which make it easy to port existing CUDA codes to the HIP layer, with no loss of performance as compared to the original CUDA application. HIP is not intended to be a drop-in replacement for CUDA, and developers should expect to do some manual coding and performance tuning work to complete the port. ## More Info: - [HIP FAQ](docs/markdown/hip_faq.md) - [HIP Kernel Language](docs/markdown/hip_kernel_language.md) -- [HIP Runtime API (Doxygen)](docs/RuntimeAPI/html/group__API.html) +- [HIP Runtime API (Doxygen)](http://gpuopen-professionalcompute-tools.github.io/HIP) - [HIP Porting Guide](docs/markdown/hip_porting_guide.md) - [HIP Terminology](docs/markdown/hip_terms.md) (including Rosetta Stone of GPU computing terms across CUDA/HIP/HC/AMP/OpenL) +- [Release Notes](RELEASE.md) ## How do I get set up? ### Prerequisites - Choose Your Platform -HIP code can be developed either on AMD HSA or Boltzmann platform using HCC compiler, or a CUDA platform with NVCC installed: +HIP code can be developed either on AMD HSA or Boltzmann platform using hcc compiler, or a CUDA platform with nvcc installed: -#### AMD (HCC): +#### AMD (hcc): -* Install HCC including supporting HSA kernel and runtime driver stack (https://bitbucket.org/multicoreware/hcc/wiki/Home). -* By default HIP looks for HCC in /opt/hcc (can be overridden by setting HCC_HOME environment variable) +* Install [hcc](https://bitbucket.org/multicoreware/hcc/wiki/Home) including supporting HSA kernel and runtime driver stack +* By default HIP looks for hcc in /opt/hcc (can be overridden by setting HCC_HOME environment variable) * By default HIP looks for HSA in /opt/hsa (can be overridden by setting HSA_PATH environment variable) -#### NVIDIA (NVCC) -* Install CUDA SDK from manufacturer website. +#### NVIDIA (nvcc) +* Install CUDA SDK from manufacturer website * By default HIP looks for CUDA SDK in /usr/local/cuda (can be overriden by setting CUDA_PATH env variable) ### Add HIP/bin to your path. -For example, if this repot is clones to ~/HIP, and you are running bash: +For example, if this repot is cloned to ~/HIP, and you are running bash: ``` > export PATH=$PATH:~/HIP/bin ``` -Verify we can find hipconfig (one of the hip tools in bin dir): +Verify your can find hipconfig (one of the hip tools in bin dir): ``` > hipconfig -pn /home/me/HIP @@ -47,14 +48,15 @@ Verify we can find hipconfig (one of the hip tools in bin dir): ## Examples and Getting Started: -* A sample that uses hipify to convert from CUDA to HIP: +* A sample and [blog](http://gpuopen.com/hip-to-be-squared-an-introductory-hip-tutorial) that uses hipify to convert a simple app from CUDA to HIP: + ```shell > cd samples/01_Intro/square # follow README / blog steps to hipify the application. ``` -* A sample written directly in HIP, showing platform specialization: +* A sample and [blog](http://gpuopen.com/platform-aware-coding-inside-hip/) demonstrating platform specialization: ```shell > cd samples/01_Intro/bit_extract > make @@ -69,13 +71,13 @@ The README with the procedures and tips the team used during this porting effort ## 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 (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. * **hcc_detail/**** , **nvcc_detail/**** : Implementation details for specific platforms. HIP applications should not include these files directly. * **bin**: Tools and scripts to help with hip porting * **hipify** : Tool to convert CUDA code to portable CPP. Converts CUDA APIs and kernel builtins. - * **hipcc** : Compiler driver that can be used to replace NVCC in existing CUDA code. hipcc ill call NVCC or HCC depending on platform, and include appropriate platform-specific headers and libraries. + * **hipcc** : Compiler driver that can be used to replace nvcc in existing CUDA code. hipcc ill call nvcc or hcc depending on platform, and include appropriate platform-specific headers and libraries. * **hipconfig** : Print HIP configuration (HIP_PATH, HIP_PLATFORM, CXX config flags, etc) * **hipexamine.sh** : Script to scan directory, find all code, and report statistics on how much can be ported with HIP (and identify likely features not yet supported) diff --git a/hipamd/RELEASE.md b/hipamd/RELEASE.md index 734bb8bbb4..605c2ee69f 100644 --- a/hipamd/RELEASE.md +++ b/hipamd/RELEASE.md @@ -2,13 +2,13 @@ Since this is an early access release and we are still in development towards the production ready version Boltzmann Driver and runtime we recommend this release be used for research and early application development. -We have attempted to document known bugs and limitations - in particular the [HIP Kernel Language](docs/markdown/hip_kernel_language.md) doc uses the phrase "Under Development", and the [HIP Runtime API](docs/RuntimeAPI/html/bug.html) lists know bugs. Some of the key items we are working on: - - Async memory copies. - - hipStream support. - - Multi-GPU - - shared-scope atomic operations. (due to compiler limitation, shared-scope map atomics map to global scope) - - Tuning built-in functions, including shfl. - - Performance optimization. +We have attempted to document known bugs and limitations - in particular the [HIP Kernel Language](docs/markdown/hip_kernel_language.md) document uses the phrase "Under Development", and the [HIP Runtime API bug list](http://gpuopen-professionalcompute-tools.github.io/HIP/bug.html) lists known bugs. Some of the key items we are working on: +- Async memory copies. +- hipStream support. +- Multi-GPU +- Shared-scope atomic operations. (due to compiler limitation, shared-scope map atomics map to global scope) +- Tuning built-in functions, including shfl. +- Performance optimization. Stay tuned - the work for many of these features is already in-flight. diff --git a/hipamd/samples/0_Intro/bit_extract/README.md b/hipamd/samples/0_Intro/bit_extract/README.md index 025b7d3072..76f8906595 100644 --- a/hipamd/samples/0_Intro/bit_extract/README.md +++ b/hipamd/samples/0_Intro/bit_extract/README.md @@ -2,3 +2,5 @@ Show an application written directly in HIP which uses platform-specific check on __HIP_PLATFORM_HCC__ to enable use of an instruction that only exists on the HCC platform. + +See related [blog](http://gpuopen.com/platform-aware-coding-inside-hip/) demonstrating platform specialization. diff --git a/hipamd/samples/0_Intro/square/README.md b/hipamd/samples/0_Intro/square/README.md index 59f59e7164..8f9aec73cb 100644 --- a/hipamd/samples/0_Intro/square/README.md +++ b/hipamd/samples/0_Intro/square/README.md @@ -1,6 +1,7 @@ # Square.md -Simple test which shows how to use hipify to port CUDA code to HIP. Covered in more detail in blog. +Simple test which shows how to use hipify to port CUDA code to HIP. +See related [blog](http://gpuopen.com/hip-to-be-squared-an-introductory-hip-tutorial) that explains the example. 1. Add hip/bin path to the PATH : export PATH=$PATH:[MYHIP]/bin