AI/rocm-systems
2
0 Forka 0
Codice Problemi Pull Request Actions Pacchetti Progetti Rilasci Wiki Attività

SWDEV-541514 - Docs update 2025-09-15 (#993)

Sfoglia il codice sorgente 
Co-authored-by: Julia Jiang <56359287+jujiang-del@users.noreply.github.com>
This commit is contained in:
Istvan KisseJulia Jiang authored and GitHub committed 2025-09-24 09:57:00 -07:00
1 parent 0575606e49
commit 83fb0c8c47
39 files changed
+2973 -807
Scarica il file Patch Scarica il file Diff Expand all files Collapse all files

No files matched your search

projects/hip/docs/install/build.rst
+115 -109
Vedi File
@@ -9,27 +9,28 @@ Build HIP from source
Prerequisites
=================================================
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with ``nvcc`` installed.
Before building and running HIP, make sure drivers and prebuilt packages are installed properly on the platform.
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler,
or a CUDA platform with ``nvcc`` installed. Before building and running HIP,
make sure drivers and prebuilt packages are installed properly on the platform.
You also need to install Python 3, which includes the ``CppHeaderParser`` package.
Install Python 3 using the following command:
.. code-block:: shell
apt-get install python3
apt-get install python3
Check and install ``CppHeaderParser`` package using the command:
.. code-block:: shell
pip3 install CppHeaderParser
pip3 install CppHeaderParser
Install ``ROCm LLVM`` package using the command:
.. code-block:: shell
apt-get install rocm-llvm-dev
apt-get install rocm-llvm-dev
.. _Building the HIP runtime:
@@ -52,169 +53,174 @@ Set the repository branch using the variable: ``ROCM_BRANCH``. For example, for
.. tab-set::
.. tab-item:: AMD
:sync: amd
.. tab-item:: AMD
:sync: amd
#. Get HIP source code.
#. Get HIP source code.
.. code-block:: shell
.. code-block:: shell
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
#. Set the environment variables.
#. Set the environment variables.
.. code-block:: shell
.. code-block:: shell
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)"
export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)"
export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
#. Build HIP.
#. Build HIP.
.. code-block:: shell
.. code-block:: shell
cd "$CLR_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
make -j$(nproc)
sudo make install
cd "$CLR_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
make -j$(nproc)
sudo make install
.. note::
.. note::
If ``CMAKE_INSTALL_PREFIX`` is not explicitly specified, the HIP runtime will be installed at
``<ROCM_PATH>``, which is by default at the path ``/opt/rocm``.
If ``CMAKE_INSTALL_PREFIX`` is not explicitly specified, the HIP runtime will be installed at
``<ROCM_PATH>``, which is by default at the path ``/opt/rocm``.
By default, the release version of HIP is built. If you need a debug version, you can put the option ``CMAKE_BUILD_TYPE=Debug`` in the command line.
By default, the release version of HIP is built. If you need a debug version, you can put the option ``CMAKE_BUILD_TYPE=Debug`` in the command line.
Default paths and environment variables:
* HIP is installed into ``<ROCM_PATH>``. This can be overridden by setting the ``INSTALL_PREFIX`` as the command option.
environment variable.
* HSA is in ``<ROCM_PATH>``. This can be overridden by setting the ``HSA_PATH``
environment variable.
* Clang is in ``<ROCM_PATH>/llvm/bin``. This can be overridden by setting the
``HIP_CLANG_PATH`` environment variable.
* The device library is in ``<ROCM_PATH>/lib``. This can be overridden by setting the
``DEVICE_LIB_PATH`` environment variable.
* Optionally, you can add ``<ROCM_PATH>/bin`` to your ``PATH``, which can make it easier to
use the tools.
* Optionally, you can set ``HIPCC_VERBOSE=7`` to output the command line for compilation.
Default paths and environment variables:
* HIP is installed into ``<ROCM_PATH>``. This can be overridden by setting the ``INSTALL_PREFIX`` as the command option.
After you run the ``make install`` command, HIP is installed to ``<ROCM_PATH>`` by default, or ``$PWD/install/hip`` while ``INSTALL_PREFIX`` is defined.
* HSA is in ``<ROCM_PATH>``. This can be overridden by setting the ``HSA_PATH``
environment variable.
#. Generate a profiling header after adding/changing a HIP API.
* Clang is in ``<ROCM_PATH>/llvm/bin``. This can be overridden by setting the
``HIP_CLANG_PATH`` environment variable.
When you add or change a HIP API, you may need to generate a new ``hip_prof_str.h`` header.
This header is used by ROCm tools to track HIP APIs, such as ``rocprofiler`` and ``roctracer``.
* The device library is in ``<ROCM_PATH>/lib``. This can be overridden by setting the
``DEVICE_LIB_PATH`` environment variable.
To generate the header after your change, use the ``hip_prof_gen.py`` tool located in
``hipamd/src``.
* Optionally, you can add ``<ROCM_PATH>/bin`` to your ``PATH``, which can make it easier to
use the tools.
Usage:
* Optionally, you can set ``HIPCC_VERBOSE=7`` to output the command line for compilation.
.. code-block:: shell
After you run the ``make install`` command, HIP is installed to ``<ROCM_PATH>`` by default, or ``$PWD/install/hip`` while ``INSTALL_PREFIX`` is defined.
`hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]`
#. Generate a profiling header after adding/changing a HIP API.
Flags:
When you add or change a HIP API, you may need to generate a new ``hip_prof_str.h`` header.
This header is used by ROCm tools to track HIP APIs, such as ``rocprofiler`` and ``roctracer``.
* ``-v``: Verbose messages
* ``-r``: Process source directory recursively
* ``-t``: API types matching check
* ``--priv``: Private API check
* ``-e``: On error exit mode
* ``-p``: ``HIP_INIT_API`` macro patching mode
To generate the header after your change, use the ``hip_prof_gen.py`` tool located in
``hipamd/src``.
Example usage:
Usage:
.. code-block:: shell
.. code-block:: shell
hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new
`hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]`
.. tab-item:: NVIDIA
:sync: nvidia
Flags:
#. Get the HIP source code.
* ``-v``: Verbose messages
* ``-r``: Process source directory recursively
* ``-t``: API types matching check
* ``--priv``: Private API check
* ``-e``: On error exit mode
* ``-p``: ``HIP_INIT_API`` macro patching mode
.. code-block:: shell
Example usage:
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
.. code-block:: shell
#. Set the environment variables.
hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new
.. code-block:: shell
.. tab-item:: NVIDIA
:sync: nvidia
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)"
export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
export HIP_OTHER="$(readlink -f rocm-systems/projects/hipother)"
#. Get the HIP source code.
#. Build HIP.
.. code-block:: shell
.. code-block:: shell
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
cd "$CLR_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF -DHIPNV_DIR=$HIP_OTHER/hipnv ..
make -j$(nproc)
sudo make install
#. Set the environment variables.
.. code-block:: shell
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)"
export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
export HIP_OTHER="$(readlink -f rocm-systems/projects/hipother)"
#. Build HIP.
.. code-block:: shell
cd "$CLR_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF -DHIPNV_DIR=$HIP_OTHER/hipnv ..
make -j$(nproc)
sudo make install
Build HIP tests
=================================================
.. tab-set::
.. tab-item:: AMD
:sync: amd
.. tab-item:: AMD
:sync: amd
* Build HIP catch tests.
**Build HIP catch tests.**
HIP catch tests utilize the Catch2 testing framework.
HIP catch tests utilize the Catch2 testing framework.
* Get HIP tests source code.
#. Get HIP tests source code.
.. code-block:: shell
.. code-block:: shell
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
export HIPTESTS_DIR="$(readlink -f rocm-systems/projects/hip-tests)"
git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
export HIPTESTS_DIR="$(readlink -f rocm-systems/projects/hip-tests)"
* Build HIP tests from source.
#. Build HIP tests from source.
.. code-block:: shell
.. code-block:: shell
cd "$HIPTESTS_DIR"
mkdir -p build; cd build
cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # or any path where HIP is installed; for example: ``/opt/rocm``
export ROCM_PATH=/opt/rocm
make build_tests
ctest # run tests
cd "$HIPTESTS_DIR"
mkdir -p build; cd build
cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # or any path where HIP is installed; for example: ``/opt/rocm``
export ROCM_PATH=/opt/rocm
make build_tests
ctest # run tests
HIP catch tests are built in ``$HIPTESTS_DIR/build``.
HIP catch tests are built in ``$HIPTESTS_DIR/build``.
To run any single catch test, use this example:
To run any single catch test, use this example:
.. code-block:: shell
.. code-block:: shell
cd $HIPTESTS_DIR/build/catch_tests/unit/texture
./TextureTest
cd $HIPTESTS_DIR/build/catch_tests/unit/texture
./TextureTest
* Build a HIP Catch2 standalone test.
#. Build a HIP Catch2 standalone test.
.. code-block:: shell
.. code-block:: shell
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
...
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
...
All tests passed
All tests passed
.. tab-item:: NVIDIA
:sync: nvidia
.. tab-item:: NVIDIA
:sync: nvidia
The commands to build HIP tests on an NVIDIA platform are the same as on an AMD platform.
However, you must first set ``-DHIP_PLATFORM=nvidia``.
The commands to build HIP tests on an NVIDIA platform are the same as on an AMD platform.
However, you must first set ``-DHIP_PLATFORM=nvidia``.
Run HIP
projects/hip/docs/install/install.rst
+58 -54
Vedi File
@@ -10,10 +10,10 @@ HIP can be installed on AMD (ROCm with HIP-Clang) and NVIDIA (CUDA with NVCC) pl
.. note::
The version definition for the HIP runtime is different from CUDA. On AMD
platforms, the :cpp:func:`hipRuntimeGetVersion` function returns the HIP
runtime version. On NVIDIA platforms, this function returns the CUDA runtime
version.
The version definition for the HIP runtime is different from CUDA. On AMD
platforms, the :cpp:func:`hipRuntimeGetVersion` function returns the HIP
runtime version. On NVIDIA platforms, this function returns the CUDA runtime
version.
.. _install_prerequisites:
@@ -22,84 +22,88 @@ Prerequisites
.. tab-set::
.. tab-item:: AMD
:sync: amd
.. tab-item:: AMD
:sync: amd
Refer to the Prerequisites section in the ROCm install guides:
Refer to the Prerequisites section in the ROCm install guides:
* :doc:`rocm-install-on-linux:reference/system-requirements`
* :doc:`rocm-install-on-windows:reference/system-requirements`
* `System requirements (Linux) <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`_
* `System requirements (Windows) <https://rocm.docs.amd.com/projects/install-on-windows/en/latest/reference/system-requirements.html>`_
.. tab-item:: NVIDIA
:sync: nvidia
.. tab-item:: NVIDIA
:sync: nvidia
With NVIDIA GPUs, HIP requires unified memory. All CUDA-enabled NVIDIA
GPUs with compute capability 5.0 or later should be supported. For more
information, see `NVIDIA's list of CUDA enabled GPUs <https://developer.nvidia.com/cuda-gpus>`_.
With NVIDIA GPUs, HIP requires unified memory. All CUDA-enabled NVIDIA
GPUs with compute capability 5.0 or later should be supported. For more
information, see `NVIDIA's list of CUDA enabled GPUs <https://developer.nvidia.com/cuda-gpus>`_.
Installation
=======================================
.. tab-set::
.. tab-item:: AMD
:sync: amd
.. tab-item:: AMD
:sync: amd
HIP is automatically installed during the ROCm installation. If you haven't yet installed ROCm, you
can find installation instructions here:
HIP is automatically installed during the ROCm installation. If you haven't
yet installed ROCm, you can find installation instructions here:
* :doc:`rocm-install-on-linux:index`
* :doc:`rocm-install-on-windows:index`
* `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/index.html>`_
* `HIP SDK installation for Windows <https://rocm.docs.amd.com/projects/install-on-windows/en/latest/index.html>`_
By default, HIP is installed into ``/opt/rocm``.
By default, HIP is installed into ``/opt/rocm``.
.. note::
There is no autodetection for the HIP installation. If you choose to install it somewhere other than the default location, you must set the ``HIP_PATH`` environment variable as explained in `Build HIP from source <./build.html>`_.
.. note::
There is no autodetection for the HIP installation. If you choose to
install it somewhere other than the default location, you must set the
``HIP_PATH`` environment variable as explained in
`Build HIP from source <./build.html>`_.
.. tab-item:: NVIDIA
:sync: nvidia
.. tab-item:: NVIDIA
:sync: nvidia
#. Install the NVIDIA toolkit.
#. Install the NVIDIA toolkit.
The latest release can be found here:
`CUDA Toolkit <https://developer.nvidia.com/cuda-downloads>`_.
The latest release can be found here:
`CUDA Toolkit <https://developer.nvidia.com/cuda-downloads>`_.
#. Setup the radeon repo.
#. Setup the radeon repo.
.. code-block::shell
.. code-block::shell
# Replace url with appropriate link in the table below
wget https://repo.radeon.com/amdgpu-install/6.2/distro/version_name/amdgpu-install_6.2.60200-1_all.deb
sudo apt install ./amdgpu-install_6.2.60200-1_all.deb
sudo apt update
# Replace url with appropriate link in the table below
wget https://repo.radeon.com/amdgpu-install/6.2/distro/version_name/amdgpu-install_6.2.60200-1_all.deb
sudo apt install ./amdgpu-install_6.2.60200-1_all.deb
sudo apt update
.. list-table:: amdgpu-install links
:widths: 25 100
:header-rows: 1
.. list-table:: amdgpu-install links
:widths: 25 100
:header-rows: 1
* - Ubuntu version
- URL
* - 24.04
- https://repo.radeon.com/amdgpu-install/6.2.4/ubuntu/noble/amdgpu-install_6.2.60204-1_all.deb
* - 22.04
- https://repo.radeon.com/amdgpu-install/6.2.4/ubuntu/jammy/amdgpu-install_6.2.60204-1_all.deb
* - Ubuntu version
- URL
* - 24.04
- https://repo.radeon.com/amdgpu-install/6.2.4/ubuntu/noble/amdgpu-install_6.2.60204-1_all.deb
* - 22.04
- https://repo.radeon.com/amdgpu-install/6.2.4/ubuntu/jammy/amdgpu-install_6.2.60204-1_all.deb
#. Install the ``hip-runtime-nvidia`` and ``hip-dev`` packages. This installs the CUDA SDK and HIP
porting layer.
#. Install the ``hip-runtime-nvidia`` and ``hip-dev`` packages. This installs the CUDA SDK and HIP
porting layer.
.. code-block:: shell
.. code-block:: shell
apt-get install hip-runtime-nvidia hip-dev
apt-get install hip-runtime-nvidia hip-dev
The default paths are:
* CUDA SDK: ``/usr/local/cuda``
* HIP: ``/opt/rocm``
The default paths are:
* CUDA SDK: ``/usr/local/cuda``
* HIP: ``/opt/rocm``
#. Set the HIP_PLATFORM to nvidia.
#. Set the HIP_PLATFORM to nvidia.
.. code-block:: shell
.. code-block:: shell
export HIP_PLATFORM="nvidia"
export HIP_PLATFORM="nvidia"
Verify your installation
==========================================================
@@ -108,4 +112,4 @@ Run ``hipconfig`` in your installation path.
.. code-block:: shell
/opt/rocm/bin/hipconfig --full
/opt/rocm/bin/hipconfig --full