SWDEV-406233 - porting documentation update into 5.7 branch

Change-Id: Id0d41b30ebdd04e8bb93989c6262063bc329e0d6
ROCm · Aug 15, 2023 · 8068116 · 8068116
1 parent c1d95f4
commit 8068116
Show file tree

Hide file tree

Showing 12 changed files with 257 additions and 166 deletions.
diff --git a/README.md b/README.md
@@ -7,16 +7,16 @@ Key features include:
 * HIP is very thin and has little or no performance impact over coding directly in CUDA 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](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/master/README.md) tools automatically convert source from CUDA to HIP.
+* The [HIPIFY](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/amd-staging/README.md) tools automatically convert source from CUDA to HIP.
 * Developers can specialize for the platform (CUDA or AMD) to tune for performance or handle tricky cases.
 
 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.
 
 ## DISCLAIMER
 
-The information presented in this document is for informational purposes only and may contain technical inaccuracies, omissions, and typographical errors. The information contained herein is subject to change and may be rendered inaccurate for many reasons, including but not limited to product and roadmap changes, component and motherboard versionchanges, new model and/or product releases, product differences between differing manufacturers, software changes, BIOS flashes, firmware upgrades, or the like. Any computer system has risks of security vulnerabilities that cannot be completely prevented or mitigated.AMD assumes no obligation to update or otherwise correct or revise this information. However, AMD reserves the right to revise this information and to make changes from time to time to the content hereof without obligation of AMD to notify any person of such revisions or changes.THIS INFORMATION IS PROVIDED ‘AS IS.” AMD MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND ASSUMES NO RESPONSIBILITY FOR ANY INACCURACIES, ERRORS, OR OMISSIONS THAT MAY APPEAR IN THIS INFORMATION. AMD SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL AMD BE LIABLE TO ANY PERSON FOR ANY RELIANCE, DIRECT, INDIRECT, SPECIAL, OR OTHER CONSEQUENTIAL DAMAGES ARISING FROM THE USE OF ANY INFORMATION CONTAINED HEREIN, EVEN IF AMD IS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. AMD, the AMD Arrow logo, and combinations thereof are trademarks of Advanced Micro Devices, Inc. Other product names used in this publication are for identification purposes only and may be trademarks of their respective companies.
+The information presented in this document is for informational purposes only and may contain technical inaccuracies, omissions, and typographical errors. The information contained herein is subject to change and may be rendered inaccurate for many reasons, including but not limited to product and roadmap changes, component and motherboard versionchanges, new model and/or product releases, product differences between differing manufacturers, software changes, BIOS flashes, firmware upgrades, or the like. Any computer system has risks of security vulnerabilities that cannot be completely prevented or mitigated.AMD assumes no obligation to update or otherwise correct or revise this information. However, AMD reserves the right to revise this information and to make changes from time to time to the content hereof without obligation of AMD to notify any person of such revisions or changes.THIS INFORMATION IS PROVIDED 'AS IS." AMD MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND ASSUMES NO RESPONSIBILITY FOR ANY INACCURACIES, ERRORS, OR OMISSIONS THAT MAY APPEAR IN THIS INFORMATION. AMD SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL AMD BE LIABLE TO ANY PERSON FOR ANY RELIANCE, DIRECT, INDIRECT, SPECIAL, OR OTHER CONSEQUENTIAL DAMAGES ARISING FROM THE USE OF ANY INFORMATION CONTAINED HEREIN, EVEN IF AMD IS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. AMD, the AMD Arrow logo, and combinations thereof are trademarks of Advanced Micro Devices, Inc. Other product names used in this publication are for identification purposes only and may be trademarks of their respective companies.
 
-© 2023 Advanced Micro Devices, Inc. All Rights Reserved.
+(C) 2023 Advanced Micro Devices, Inc. All Rights Reserved.
 
 ## Repository branches:
 

diff --git a/docs/.doxygen/mainpage.md b/docs/.doxygen/mainpage.md
@@ -11,6 +11,7 @@ This is the full HIP Runtime API reference. The API is organized into
 - @ref Error
 - @ref Stream
 - @ref StreamM
+- @ref Event
 - @ref Memory
   - @ref External
   - @ref MemoryM
@@ -29,4 +30,4 @@ This is the full HIP Runtime API reference. The API is organized into
 - @ref Graph
 - @ref Virtual
 - @ref GL
-- [Surface Object](#Surface)
+- @ref Surface
diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -5,7 +5,7 @@ subtrees:
     - file: user_guide/programming_manual
     - file: user_guide/hip_rtc
     - file: user_guide/faq
-    - file: user_guide/hip_porting_guide    
+    - file: user_guide/hip_porting_guide
     - file: user_guide/hip_porting_driver_api
 - caption: How to Guides
   entries:
@@ -23,4 +23,4 @@ subtrees:
   entries:
   - file: developer_guide/build
   - file: developer_guide/logging
-  - file: developer_guide/contributing.md
+  - file: developer_guide/contributing.md
diff --git a/docs/developer_guide/build.md b/docs/developer_guide/build.md
@@ -13,6 +13,7 @@ sudo apt install mesa-common-dev
 sudo apt install clang
 sudo apt install comgr
 sudo apt-get -y install rocm-dkms
+sudo apt-get install -y libelf-dev
 ```
 
 ### NVIDIA platform
@@ -22,14 +23,14 @@ Install Nvidia driver and pre-build packages (see HIP Installation Guide at http
 ### Branch of repository
 
 Before get HIP source code, set the expected branch of repository at the variable `ROCM_BRANCH`.
-For example, for ROCm5.0 release branch, set
+For example, for ROCm5.7 release branch, set
 ```shell
-export ROCM_BRANCH=rocm-5.0.x
+export ROCM_BRANCH=rocm-5.7.x
 ```
 
-ROCm5.4 release branch, set
+ROCm5.6 release branch, set
 ```shell
-export ROCM_BRANCH=rocm-5.4.x
+export ROCM_BRANCH=rocm-5.6.x
 ```
 Similiar format for future branches.
 
@@ -42,38 +43,46 @@ Similiar format for future branches.
 ### Get HIP source code
 
 ```shell
-git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hipamd.git
+git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/clr.git
 git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git
-git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/ROCclr.git
-git clone -b "$ROCM_BRANCH" https://github.com/RadeonOpenCompute/ROCm-OpenCL-Runtime.git
+git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/HIPCC.git
 ```
 
 ### Set the environment variables
 
 ```shell
-export HIPAMD_DIR="$(readlink -f hipamd)"
+export CLR_DIR="$(readlink -f clr)"
 export HIP_DIR="$(readlink -f hip)"
+export HIPCC_DIR="$(readlink -f hipcc)"
 ```
 
-ROCclr is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends.
-See https://github.com/ROCm-Developer-Tools/ROCclr
+Note, starting from ROCM 5.6 release, clr is a new repository including the previous ROCclr, HIPAMD and OpenCl repositories.
+ROCclr is defined on AMD platform that HIP uses Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends.
+HIPAMD provides implementation specifically for AMD platform.
+OpenCL provides headers that ROCclr runtime currently depends on.
 
-HIPAMD repository provides implementation specifically for AMD platform.
-See https://github.com/ROCm-Developer-Tools/hipamd
+### Build the HIPCC runtime
+
+```shell
+cd "$HIPCC_DIR"
+mkdir -p build; cd build
+cmake ..
+make -j4
+```
 
 ### Build HIP
 
 ```shell
-cd "$HIPAMD_DIR"
+cd "$CLR_DIR"
 mkdir -p build; cd build
-cmake -DHIP_COMMON_DIR=$HIP_DIR -DCMAKE_PREFIX_PATH="<ROCM_PATH>/" -DCMAKE_INSTALL_PREFIX=$PWD/install ..
+cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
+
 make -j$(nproc)
 sudo make install
 ```
-::::{note}
-If you don't specify `CMAKE_INSTALL_PREFIX`, hip runtime will be installed to `<ROCM_PATH>/hip`.
-By default, release version of AMDHIP is built.
-::::
+
+Note, if `CMAKE_INSTALL_PREFIX` is not specified, hip runtime will be installed to `<ROCM_PATH>/hip`.
+By default, release version of HIP is built.
 
 ### Default paths and environment variables
 
@@ -120,9 +129,9 @@ Developers can build HIP directed tests right after build HIP commands,
 sudo make install
 make -j$(nproc) build_tests
 ```
-By default, all HIP directed tests will be built and generated under the folder `$HIPAMD_DIR/build/`directed_tests.
+By default, all HIP directed tests will be built and generated under the folder `$CLR_DIR/build/hipamd`directed_tests.
 Take HIP directed device APIs tests, as an example, all available test applications will have executable files generated under,
-`$HIPAMD_DIR/build/directed_tests/runtimeApi/device`.
+`$CLR_DIR/build/hipamd/directed_tests/runtimeApi/device`.
 
 Run all HIP directed_tests, use the command,
 
@@ -138,7 +147,7 @@ Build and run a single directed test, use the follow command as an example,
 
 ```shell
 make directed_tests.texture.hipTexObjPitch
-cd $HIPAMD_DIR/build/directed_tests/texcture
+cd $CLR_DIR/build/hipamd/directed_tests/texcture
 ./hipTexObjPitch
 ```
 Please note, the integrated HIP directed tests, will be deprecated in future release.
@@ -156,20 +165,20 @@ git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip-tests.gi
 ##### Build HIP tests from source
 
 ```shell
-export HIP_TESTS_DIR="$(readlink -f hip-tests)"
-cd "$HIP_TESTS_DIR"
+export HIPTESTS_DIR="$(readlink -f hip-tests)"
+cd "$HIPTESTS_DIR"
 mkdir -p build; cd build
-export HIP_PATH=$HIPAMD_DIR/build/install (or any path where HIP is installed, for example, /opt/rocm)
+export HIP_PATH=$CLR_DIR/build/install (or any path where HIP is installed, for example, /opt/rocm)
 cmake ../catch/ -DHIP_PLATFORM=amd
 make -j$(nproc) build_tests
 ctest # run tests
 ```
-HIP catch tests are built under the folder $HIP_TESTS_DIR/build.
+HIP catch tests are built under the folder $HIPTESTS_DIR/build.
 
 To run any single catch test, the following is an example,
 
 ```shell
-cd $HIP_TESTS_DIR/build/catch_tests/unit/texture
+cd $HIPTESTS_DIR/build/catch_tests/unit/texture
 ./TextureTest
 ```
 
@@ -178,8 +187,8 @@ cd $HIP_TESTS_DIR/build/catch_tests/unit/texture
 HIP Catch2 supports build a standalone test, for example,
 
 ```shell
-cd "$HIP_TESTS_DIR"
-hipcc $HIP_TESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc -I ./catch/include ./catch/hipTestMain/standalone_main.cc -I ./catch/external/Catch2 -o hipPointerGetAttributes
+cd "$HIPTESTS_DIR"
+hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc -I ./catch/include ./catch/hipTestMain/standalone_main.cc -I ./catch/external/Catch2 -o hipPointerGetAttributes
 ./hipPointerGetAttributes
 ...
 
@@ -193,22 +202,33 @@ All tests passed
 
 ```shell
 git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git
-git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hipamd.git
+git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/clr.git
+git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/HIPCC.git
 ```
 
 ### Set the environment variables
 
 ```shell
 export HIP_DIR="$(readlink -f hip)"
-export HIPAMD_DIR="$(readlink -f hipamd)"
+export CLR_DIR="$(readlink -f hipamd)"
+export HIPCC_DIR="$(readlink -f hipcc)"
 ```
 
-### Build HIP
+### Build the HIPCC runtime
+
+```shell
+cd "$HIPCC_DIR"
+mkdir -p build; cd build
+cmake ..
+make -j4
+```
+
+## Build HIP
 
 ```shell
-cd "$HIPAMD_DIR"
+cd "$CLR_DIR"
 mkdir -p build; cd build
-cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install ..
+cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
 make -j$(nproc)
 sudo make install
 ```
@@ -218,5 +238,5 @@ Build HIP tests commands on NVIDIA platform are basically the same as AMD, excep
 
 ## Run HIP
 
-Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-5.0.x/samples/0_Intro/square).
+Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/hip-tests/tree/rocm-5.5.x/samples/0_Intro/square).
 
diff --git a/docs/developer_guide/logging.md b/docs/developer_guide/logging.md
@@ -85,8 +85,7 @@ ClPrint(amd::LOG_INFO, amd::LOG_INIT, "Initializing HSA stack.");
 
 ## HIP Logging Example:
 
-Below is an example to enable HIP logging and get logging information during
-execution of hipinfo,
+Below is an example to enable HIP logging and get logging information during execution of hipinfo on Linux,
 
 ```console
 user@user-test:~/hip/bin$ export AMD_LOG_LEVEL=4
@@ -136,22 +135,7 @@ concurrentKernels:                1
 cooperativeLaunch:                0
 cooperativeMultiDeviceLaunch:     0
 arch.hasGlobalInt32Atomics:       1
-arch.hasGlobalFloatAtomicExch:    1
-arch.hasSharedInt32Atomics:       1
-arch.hasSharedFloatAtomicExch:    1
-arch.hasFloatAtomicAdd:           1
-arch.hasGlobalInt64Atomics:       1
-arch.hasSharedInt64Atomics:       1
-arch.hasDoubles:                  1
-arch.hasWarpVote:                 1
-arch.hasWarpBallot:               1
-arch.hasWarpShuffle:              1
-arch.hasFunnelShift:              0
-arch.hasThreadFenceSystem:        1
-arch.hasSyncThreadsExt:           0
-arch.hasSurfaceFuncs:             0
-arch.has3dGrid:                   1
-arch.hasDynamicParallelism:       0
+...
 gcnArch:                          1012
 isIntegrated:                     0
 maxTexture1D:                     65536
@@ -178,6 +162,54 @@ memInfo.total:                    7.98 GB
 memInfo.free:                     7.98 GB (100%)
 ```
 
+On Windows, AMD_LOG_LEVEL can be set via environment variable from advanced system setting, or from Command prompt run as administrator, as shown below as an example, which shows some debug log information calling backend runtime on Windows.
+```console
+C:\hip\bin>set AMD_LOG_LEVEL=4
+C:\hip\bin>hipinfo
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\comgrctx.cpp:33  : 605413686305 us: 29864: [tid:0x9298] Loading COMGR library.
+:4:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\platform\runtime.cpp:83  : 605413869411 us: 29864: [tid:0x9298] init
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_context.cpp:47  : 605413869502 us: 29864: [tid:0x9298] Direct Dispatch: 0
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device_runtime.cpp:543 : 605413870553 us: 29864: [tid:0x9298] hipGetDeviceCount: Returned hipSuccess :
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device_runtime.cpp:556 : 605413870631 us: 29864: [tid:0x9298] <-[32m hipSetDevice ( 0 ) <-[0m
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device_runtime.cpp:561 : 605413870848 us: 29864: [tid:0x9298] hipSetDevice: Returned hipSuccess :
+--------------------------------------------------------------------------------
+device#                           0
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device.cpp:346 : 605413871623 us: 29864: [tid:0x9298] <-[32m hipGetDeviceProperties ( 0000008AEBEFF8C8, 0 ) <-[0m
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device.cpp:348 : 605413871695 us: 29864: [tid:0x9298] hipGetDeviceProperties: Returned hipSuccess :
+Name:                             AMD Radeon(TM) Graphics
+pciBusID:                         3
+pciDeviceID:                      0
+pciDomainID:                      0
+multiProcessorCount:              7
+maxThreadsPerMultiProcessor:      2560
+isMultiGpuBoard:                  0
+clockRate:                        1600 Mhz
+memoryClockRate:                  1333 Mhz
+memoryBusWidth:                   0
+totalGlobalMem:                   12.06 GB
+totalConstMem:                    2147483647
+sharedMemPerBlock:                64.00 KB
+...
+gcnArchName:                      gfx90c:xnack-
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device_runtime.cpp:541 : 605413924779 us: 29864: [tid:0x9298] <-[32m hipGetDeviceCount ( 0000008AEBEFF8A4 ) <-[0m
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_device_runtime.cpp:543 : 605413925075 us: 29864: [tid:0x9298] hipGetDeviceCount: Returned hipSuccess :
+peers:                            :3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_peer.cpp:176 : 605413928643 us: 29864: [tid:0x9298] <-[32m hipDeviceCanAccessPeer ( 0000008AEBEFF890, 0, 0 ) <-[0m
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_peer.cpp:177 : 605413928743 us: 29864: [tid:0x9298] hipDeviceCanAccessPeer: Returned hipSuccess :
+non-peers:                        :3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_peer.cpp:176 : 605413930830 us: 29864: [tid:0x9298] <-[32m hipDeviceCanAccessPeer ( 0000008AEBEFF890, 0, 0 ) <-[0m
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_peer.cpp:177 : 605413930882 us: 29864: [tid:0x9298] hipDeviceCanAccessPeer: Returned hipSuccess :
+device#0
+...
+:4:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\pal\palmemory.cpp:430 : 605414517802 us: 29864: [tid:0x9298] Free-:     8000 bytes, VM[ 3007c8000,  3007d0000]
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\devprogram.cpp:2979: 605414517893 us: 29864: [tid:0x9298] For Init/Fini: Kernel Name: __amd_rocclr_copyBufferToImage
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\devprogram.cpp:2979: 605414518259 us: 29864: [tid:0x9298] For Init/Fini: Kernel Name: __amd_rocclr_copyBuffer
+...
+:4:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\pal\palmemory.cpp:206 : 605414523422 us: 29864: [tid:0x9298] Alloc: 100000 bytes, ptr[00000003008D0000-00000003009D0000], obj[00000003007D0000-00000003047D0000]
+:4:C:\constructicon\builds\gfx\two\22.40\drivers\compute\vdi\device\pal\palmemory.cpp:206 : 605414523767 us: 29864: [tid:0x9298] Alloc: 100000 bytes, ptr[00000003009D0000-0000000300AD0000], obj[00000003007D0000-00000003047D0000]
+:3:C:\constructicon\builds\gfx\two\22.40\drivers\compute\hipamd\src\hip_memory.cpp:681 : 605414524092 us: 29864: [tid:0x9298] hipMemGetInfo: Returned hipSuccess :
+memInfo.total:                    12.06 GB
+memInfo.free:                     11.93 GB (99%)
+```
+
 ## HIP Logging Tips:
 
 - HIP logging works for both release and debug version of HIP application.
@@ -191,3 +223,4 @@ memInfo.free:                     7.98 GB (100%)
 user@user-test:~/hip/bin$ ./hipinfo > ~/hip_log.txt
 ```
 
+