SWDEV-467739 - Adding CLR landing page in HIP

Change-Id: I3e21520d37ae0c408d1f401b2dd849a098bbc818 [ROCm/hip commit: f39473f692]
2024-06-18 17:04:04 -04:00
@@ -111,13 +111,13 @@ The HIP Runtime API code and compute kernel definition can exist in the same sou

 HIP C++ code can be compiled with either,

-* On the NVIDIA CUDA platform, HIP provides header file which translate from the HIP runtime APIs to CUDA runtime APIs.  The header file contains mostly inlined
+* On the NVIDIA CUDA platform, HIP provides header file in the repository [hipother](https://github.com/ROCm/hipother) which translate from the HIP runtime APIs to CUDA runtime APIs.  The header file contains mostly inlined
  functions and thus has very low overhead - developers coding in HIP should expect the same performance as coding in native CUDA.  The code is then
  compiled with nvcc, the standard C++ compiler provided with the CUDA SDK.  Developers can use any tools supported by the CUDA SDK including the CUDA
  profiler and debugger.
-* On the AMD ROCm platform, HIP provides a header and runtime library built on top of HIP-Clang compiler.  The HIP runtime implements HIP streams, events, and memory APIs,
+* On the AMD ROCm platform, HIP provides a header and runtime library built on top of HIP-Clang compiler in the repository [Common Language Runtime (CLR)](https://github.com/ROCm/clr).  The HIP runtime implements HIP streams, events, and memory APIs,
  and is a object library that is linked with the application.  The source code for all headers and the library implementation is available on GitHub.
-  HIP developers on ROCm can use AMD's ROCgdb (https://github.com/ROCm/ROCgdb) for debugging and profiling.
+  HIP developers on ROCm can use AMD's [ROCgdb](https://github.com/ROCm/ROCgdb) for debugging and profiling.

 Thus HIP source code can be compiled to run on either platform.  Platform-specific features can be isolated to a specific platform using conditional compilation.  Thus HIP
 provides source portability to either platform.   HIP provides the _hipcc_ compiler driver which will call the appropriate toolchain depending on the desired platform.
@@ -162,7 +162,7 @@ NOTE: If HIP_ROCCLR_HOME is set, there is no need to set HIP_CLANG_PATH since hi

 ## What is AMD clr?

-AMD clr (Common Language Runtime) is a repository for the AMD platform, which contains source codes for AMD's compute languages runtimes as follows,
+AMD [Common Language Runtime (CLR)](https://github.com/ROCm/clr) is a repository for the AMD platform, which contains source codes for AMD's compute languages runtimes as follows,

 * hipamd - contains implementation of HIP language for AMD GPU.
 * rocclr - contains virtual device interfaces that compute runtimes interact with backends, such as ROCr on Linux and PAL on Windows.
@@ -170,7 +170,7 @@ AMD clr (Common Language Runtime) is a repository for the AMD platform, which co

 ## What is hipother?

-A new repository 'hipother' is added in the ROCm 6.1 release, which is branched out from HIP.
+A new repository ['hipother'](https://github.com/ROCm/hipother) is added in the ROCm 6.1 release, which is branched out from HIP.
 hipother supports the HIP back-end implementation on some non-AMD platforms, like NVIDIA.

 ## Can I get HIP open source repository for Windows?
@@ -11,6 +11,10 @@ For HIP supported AMD GPUs on multiple operating systems, see:

 The CUDA enabled NVIDIA GPUs are supported by HIP. For more information, see [GPU Compute Capability](https://developer.nvidia.com/cuda-gpus).

+On the AMD ROCm platform, HIP provides header files and runtime library built on top of HIP-Clang compiler in the repository [Common Language Runtime (CLR)](./understand/amd_clr), which contains source codes for AMD's compute languages runtimes as follows,
+
+On non-AMD platforms, like NVIDIA, HIP provides header files required to support non-AMD specific back-end implementation in the repository ['hipother'](https://github.com/ROCm/hipother), which translates from the HIP runtime APIs to CUDA runtime APIs.
+
 ## Overview

 ::::{grid} 1 1 2 2
@@ -28,6 +32,7 @@ The CUDA enabled NVIDIA GPUs are supported by HIP. For more information, see [GP
 * {doc}`./understand/programming_model`
 * {doc}`./understand/programming_model_reference`
 * {doc}`./understand/hardware_implementation`
+* {doc}`./understand/amd_clr`

 :::

@@ -18,6 +18,7 @@ subtrees:
  - file: understand/programming_model
  - file: understand/programming_model_reference
  - file: understand/hardware_implementation
+  - file: understand/amd_clr

 - caption: How to
  entries:
@@ -0,0 +1,82 @@
+.. meta::
+  :description: This chapter describes the AMD CLR which is the implementation of HIP supporting on the AMD platform.
+  :keywords: AMD, ROCm, HIP, CLR, HIPAMD, OpenCL, ROCCLR, CHANGELOG
+
+.. _AMD_Compute_Language_Runtimes:
+
+*******************************************************************************
+AMD Common Language Runtimes (CLR)
+*******************************************************************************
+
+CLR contains source codes for AMD's compute languages runtimes: ``HIP`` and ``OpenCL™``.
+CLR is the part of HIP runtime which is supported on the AMD ROCm platform, it provides a header and runtime library built on top of HIP-Clang compiler.
+For developers and users, CLR implements HIP runtime APIs including streams, events, and memory APIs, which is a object library that is linked with the application.
+The source codes for all headers and the library implementation are available on GitHub in the `clr repository <https://github.com/ROCm/clr>`_.
+
+
+Project Organisation
+====================
+
+CLR includes the following source code,
+
+* ``hipamd`` - contains implementation of ``HIP`` language on the AMD platform. It is hosted at `clr/hipamd <https://github.com/ROCm/clr/tree/develop/hipamd>`_.
+
+* ``opencl`` - contains implementation of `OpenCL™ <https://www.khronos.org/opencl/>`_ on AMD platform. It is hosted at `clr/opencl <https://github.com/ROCm/clr/tree/develop/opencl>`_.
+
+* ``rocclr`` - contains common runtime used in `HIP` and `OpenCL™`. This is hosted at `clr/rocclr <https://github.com/ROCm/clr/tree/develop/rocclr>`_.
+
+
+How to build/install
+====================
+
+Prerequisites
+-------------
+
+Please refer to Quick Start Guide in `ROCm Docs <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/tutorial/quick-start.html>`_.
+
+Building CLR requires ``rocm-hip-libraries`` meta package, which provides the pre-requisites for CLR.
+
+
+Linux
+-----
+
+* Clone this repository
+
+.. code-block:: shell
+
+   cd clr && mkdir build && cd build
+
+* For ``HIP``
+
+.. code-block:: shell
+
+   cmake .. -DCLR_BUILD_HIP=ON -DHIP_COMMON_DIR=$HIP_COMMON_DIR
+
+   ``HIP_COMMON_DIR`` points to `HIP <https://github.com/ROCm/HIP>`_.
+
+* For ``OpenCL™``
+
+.. code-block:: shell
+
+   cmake .. -DCLR_BUILD_OCL=ON
+   make
+   make install
+
+
+Users can also build ``OCL`` and ``HIP`` at the same time by passing ``-DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=ON`` to configure command.
+
+For detail instructions, please refer to `build HIP <https://rocm.docs.amd.com/projects/HIP/en/latest/install/build.html>`_.
+
+
+Test
+-----
+
+``hip-tests`` is a separate repository hosted at `hip-tests <https://github.com/ROCm/hip-tests>`_.
+
+To run ``hip-tests`` please go to the repository and follow the steps.
+
+
+Release notes
+-------------
+
+HIP provides release notes in CLR `change log <https://github.com/ROCm/clr/blob/develop/CHANGELOG.md>`_, which has records of changes in each release.