From 519df7a51f2de055de70599a83cf8f30b01e497a Mon Sep 17 00:00:00 2001 From: Saad Rahim <44449863+saadrahim@users.noreply.github.com> Date: Fri, 2 Jun 2023 14:35:24 -0600 Subject: [PATCH] Refactoring installation documentation (#2202) Co-authored-by: Sam Wu --- docs/deploy/linux/index.md | 49 +- docs/deploy/linux/install_overview.md | 113 +---- docs/deploy/linux/installer/index.md | 31 ++ docs/deploy/linux/installer/install.md | 312 +++++++++++++ docs/deploy/linux/installer/uninstall.md | 27 ++ docs/deploy/linux/installer/upgrade.md | 28 ++ docs/deploy/linux/os-native/index.md | 38 ++ docs/deploy/linux/{ => os-native}/install.md | 418 +----------------- .../package_manager_integration.md | 0 .../deploy/linux/{ => os-native}/uninstall.md | 0 docs/deploy/linux/{ => os-native}/upgrade.md | 49 +- docs/deploy/linux/prerequisites.md | 44 +- docs/release/licensing.md | 20 + docs/sphinx/_toc.yml.in | 25 +- 14 files changed, 534 insertions(+), 620 deletions(-) create mode 100644 docs/deploy/linux/installer/index.md create mode 100644 docs/deploy/linux/installer/install.md create mode 100644 docs/deploy/linux/installer/uninstall.md create mode 100644 docs/deploy/linux/installer/upgrade.md create mode 100644 docs/deploy/linux/os-native/index.md rename docs/deploy/linux/{ => os-native}/install.md (57%) rename docs/deploy/linux/{ => os-native}/package_manager_integration.md (100%) rename docs/deploy/linux/{ => os-native}/uninstall.md (100%) rename docs/deploy/linux/{ => os-native}/upgrade.md (74%) diff --git a/docs/deploy/linux/index.md b/docs/deploy/linux/index.md index d50814c43..13f4275b1 100644 --- a/docs/deploy/linux/index.md +++ b/docs/deploy/linux/index.md @@ -1,18 +1,13 @@ # Deploy ROCm on Linux -Please start with {doc}`/deploy/linux/quick_start` or follow the detailed +Start with {doc}`/deploy/linux/quick_start` or follow the detailed instructions below. -::::{grid} 2 3 3 3 +## Prepare to Install + +::::{grid} 1 1 2 2 :gutter: 1 -:::{grid-item-card} Overview -:link: install_overview -:link-type: doc - -Overview and comparison of the different ways to install ROCm. -::: - :::{grid-item-card} Prerequisites :link: prerequisites :link-type: doc @@ -20,33 +15,35 @@ Overview and comparison of the different ways to install ROCm. The prerequisites page lists the required steps *before* installation. ::: -:::{grid-item-card} Installation -:link: install +:::{grid-item-card} Install Choices +:link: install_overview :link-type: doc -Detailed steps to install with the package manager or with the installation -script, including multi-version installation. Recommended for most users. +Distro Commands vs AMDGPU Installer + +Standard Packages vs Multi-Version Packages ::: -:::{grid-item-card} Upgrading -:link: upgrade +:::: + +## Choose your install method + +::::{grid} 1 1 2 2 +:gutter: 1 + +:::{grid-item-card} Distro Commands +:link: os-native/index :link-type: doc -Instructions for upgrading an existing ROCm installation. +Directly use your distribution's package manager to install ROCm. ::: -:::{grid-item-card} Uninstallation -:link: uninstall +:::{grid-item-card} AMDGPU Installer +:link: installer/index :link-type: doc -Steps for removing ROCm packages libraries and tools. -::: - -:::{grid-item-card} Package Manager Integration -:link: package_manager_integration -:link-type: doc - -Information about (meta-)packages in the ROCm ecosystem. +Use an installer tool that orchestrates changes via the package +manager. ::: :::: diff --git a/docs/deploy/linux/install_overview.md b/docs/deploy/linux/install_overview.md index 6ddd2f40c..6dbcc9c65 100644 --- a/docs/deploy/linux/install_overview.md +++ b/docs/deploy/linux/install_overview.md @@ -1,111 +1,30 @@ -# Installation Overview (Linux) +# ROCm Installation Options (Linux) -This document is intended for users familiar with Linux and discusses the -installation of ROCm on various distributions. +Users installing ROCm must choose between various installation options. A new +user should follow the [Quick Start guide](./quick_start). -The guide provides instructions for the following: +## Distro Package Manager Commands versus AMDGPU Installer? -- Kernel-mode driver installation -- ROCm single-version and multi-version installation -- ROCm and kernel-mode driver version upgrade -- ROCm single-version and multi-version uninstallation -- Kernel-mode driver uninstallation +Users can install the same packages via two CLI interfaces as follows: -```{note} -The rest of this document refers to _Radeon™ Software for Linux_ as the `amdgpu` -stack and `amdgpu-dkms` driver as the kernel-mode driver. -``` +- Linux distro package manager commands. +- a proprietary installer known as the `amdgpu-install` script -## Installation Methods +There is no difference in the final installation state when choosing either CLI. -It is customary for Linux installers to integrate into the system's package -manager. There are two notable groups of package sources: +Integrating with the distribution's package manager lets the user install, +upgrade and uninstall using familiar commands and workflows. Third party +ecosystem support is the same as your OS package manager. -- AMD-hosted repositories maintained by AMD available to register on supported - Linux distribution versions. For a complete list of AMD-supported platforms, - refer to the article: [GPU and OS Support](/release/gpu_os_support). -- Distribution-hosted repositories maintained by the developer of said Linux - distribution. These require little to no setup from the user, but aren't tested - by AMD. For support on these installations, contact the relevant maintainers. - -AMD also provides installer scripts for those that wish to drive installations -in a more manual fashion. - -## Package Licensing - -```{attention} -AQL Profiler and AOCC CPU optimization are both provided in binary form, each -subject to the license agreement enclosed in the directory for the binary and is -available here: `/opt/rocm/share/doc/rocm-llvm-alt/EULA`. By using, installing, -copying or distributing AQL Profiler and/or AOCC CPU Optimizations, you agree to -the terms and conditions of this license agreement. If you do not agree to the -terms of this agreement, do not install, copy or use the AQL Profiler and/or the -AOCC CPU Optimizations. -``` - -For the rest of the ROCm packages, you can find the licensing information at the -following location: `/opt/rocm/share/doc//` - -For example, you can fetch the licensing information of the `_amd_comgr_` -component (Code Object Manager) from the `amd_comgr` folder. A file named -`LICENSE.txt` contains the license details at: -`/opt/rocm-5.4.3/share/doc/amd_comgr/LICENSE.txt` - -### Package Manager Integration - -Integrating with the distribution's package manager let's the user install, -upgrade and uninstall using familiar commands and workflows. The actual commands -vary from distribution to distribution. For more information, refer to -[Package Manager Integration](package_manager_integration). - -### Installer Script - -The `amdgpu-install` script streamlines the installation process by: - -- Abstracting the distribution-specific package installation logic -- Performing the repository setup -- Allowing you to specify the use case and automating the installation of all - the required packages -- Installing multiple ROCm releases simultaneously on a system -- Automating updating local repository information through enhanced - functionality of the `amdgpu-install` script -- Performing post-install checks to verify whether the installation was - completed successfully -- Upgrading the installed ROCm release -- Uninstalling the installed single-version or multi-version ROCm releases - -```{tip} -The installer script is provided for convenience. It doesn't do anything the -user otherwise couldn't. It automates some tasks surrounding installation, such -as registering/unregistering and driving the system's package manager, but the -bulk of the work will still be done by the system's package manager. As is the -case with most convenience wrappers, some degree of customization is lost for -the sake of simplicity. -``` - -#### Use cases - -The installer script introduces the notion of "use cases", which denote usage -patterns or reasons why someone installs ROCm. This is to allow users to install -only a subset of the ROCm ecosystem, parts concerning them, resulting in -smaller installation footprint and faster installs/upgrades. - -Some of the ROCm-specific use cases the installer supports are: - -- OpenCL (ROCr/KFD based) runtime -- HIP runtimes -- ROCm libraries and applications -- ROCm Compiler and device libraries -- Kernel-mode driver - -For more information, refer to the How to Install ROCm section in this guide. +The `amdgpu-install` script is a wrapper around the package manager. The same +packages are installed by this script as the package manager system. (installation-types)= -## Installation types +## Standard (Single Version) ROCm install versus Multi-Version -This section discusses the single-version and multi-version installation of the -ROCm software stack. +ROCm packages are versioned with both semantic versioning that is package +specific and a ROCm release version. ### Single-version Installation diff --git a/docs/deploy/linux/installer/index.md b/docs/deploy/linux/installer/index.md new file mode 100644 index 000000000..65386807b --- /dev/null +++ b/docs/deploy/linux/installer/index.md @@ -0,0 +1,31 @@ +# AMDGPU Install Script + +::::{grid} 2 3 3 3 +:gutter: 1 + +:::{grid-item-card} Install +:link: install +:link-type: doc + +How to install ROCm? +::: + +:::{grid-item-card} Upgrade +:link: upgrade +:link-type: doc + +Instructions for upgrading an existing ROCm installation. +::: + +:::{grid-item-card} Uninstall +:link: uninstall +:link-type: doc + +Steps for removing ROCm packages libraries and tools. +::: + +:::: + +## See Also + +- {doc}`/release/gpu_os_support` diff --git a/docs/deploy/linux/installer/install.md b/docs/deploy/linux/installer/install.md new file mode 100644 index 000000000..81f7dfbf3 --- /dev/null +++ b/docs/deploy/linux/installer/install.md @@ -0,0 +1,312 @@ +# Installation (Scripted) + +(install-script-method)= + +The installer script method automates the installation process for the AMDGPU +and ROCm stack. The installer script handles the complete installation process +for ROCm, including setting up the repository, cleaning the system, updating, +and installing the desired drivers and meta-packages. Users who are +less familiar with the Linux standard commands can choose this method for ROCm +installation. + +Prior to beginning, please ensure you have the [prerequisites](../prerequisites) +installed. + +## Download and Install the Installer Script + +::::::{tab-set} +:::::{tab-item} Ubuntu +:sync: ubuntu + + +::::{rubric} To download the amdgpu-install script on the system, use the following commands. +:::: + +::::{tab-set} +:::{tab-item} Ubuntu 20.04 +:sync: ubuntu-20.04 + +```shell +sudo apt update +wget https://repo.radeon.com/amdgpu-install/5.4.3/ubuntu/focal/amdgpu-install_5.4.50403-1_all.deb +sudo apt install ./amdgpu-install_5.4.50403-1_all.deb +``` + +::: +:::{tab-item} Ubuntu 22.04 +:sync: ubuntu-22.04 + +```shell +sudo apt update +wget https://repo.radeon.com/amdgpu-install/5.4.3/ubuntu/jammy/amdgpu-install_5.4.50403-1_all.deb +sudo apt install ./amdgpu-install_5.4.50403-1_all.deb +``` + +::: +:::: +::::: +:::::{tab-item} Red Hat Enterprise Linux +:sync: RHEL + + +::::{rubric} To download the amdgpu-install script on the system, use the following commands. +:::: + +::::{tab-set} +:::{tab-item} RHEL 8.6 +:sync: RHEL-8.6 + +```shell +sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/8.6/amdgpu-install-5.4.50403-1.el8.noarch.rpm +``` + +::: +:::{tab-item} RHEL 8.7 +:sync: RHEL-8.7 + +```shell +sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/8.7/amdgpu-install-5.4.50403-1.el8.noarch.rpm +``` + +::: +:::{tab-item} RHEL 9.1 +:sync: RHEL-9.1 + +```shell +sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/9.1/amdgpu-install-5.4.50403-1.el9.noarch.rpm +``` + +::: +:::: +::::: +:::::{tab-item} SUSE Linux Enterprise Server 15 +:sync: SLES15 + + +::::{rubric} To download the amdgpu-install script on the system, use the following commands. +:::: + +::::{tab-set} +:::{tab-item} Service Pack 4 +:sync: SLES15-SP4 + +```shell +sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/5.4.3/sle/15.4/amdgpu-install-5.4.50403-1.noarch.rpm +``` + +::: +:::: +::::: +:::::: + +## Using the Installer Script for Single-version ROCm Installation + +To install use cases specific to your requirements, use the installer +`amdgpu-install` as follows: + +- To install a single use case: + + ```shell + sudo amdgpu-install --usecase=rocm + ``` + +- To install kernel-mode driver: + + ```shell + sudo amdgpu-install --usecase=dkms + ``` + +- To install multiple use cases: + + ```shell + sudo amdgpu-install --usecase=hiplibsdk,rocm + ``` + +- To display a list of available use cases: + + ```shell + sudo amdgpu-install --list-usecase + ``` + + Following is a sample of output listed by the command above: + + ```{note} + The list in this section represents only a sample of available use cases for ROCm: + ``` + + ```none + If --usecase option is not present, the default selection is "graphics,opencl,hip" + + Available use cases: + rocm(for users and developers requiring full ROCm stack) + - OpenCL (ROCr/KFD based) runtime + - HIP runtimes + - Machine learning framework + - All ROCm libraries and applications + - ROCm Compiler and device libraries + - ROCr runtime and thunk + lrt(for users of applications requiring ROCm runtime) + - ROCm Compiler and device libraries + - ROCr runtime and thunk + opencl(for users of applications requiring OpenCL on Vega or + later products) + - ROCr based OpenCL + - ROCm Language runtime + + openclsdk (for application developers requiring ROCr based OpenCL) + - ROCr based OpenCL + - ROCm Language runtime + - development and SDK files for ROCr based OpenCL + + hip(for users of HIP runtime on AMD products) + - HIP runtimes + hiplibsdk (for application developers requiring HIP on AMD products) + - HIP runtimes + - ROCm math libraries + - HIP development libraries + ``` + +```{tip} +Adding `-y` as a parameter to `amdgpu-install` skips user prompts (for +automation). Example: `amdgpu-install -y --usecase=rocm` +``` + +## Using Installer Script in Docker + +When the installation is initiated in Docker, the installer tries to install the +use case along with the kernel-mode driver. However, you cannot install the +kernel-mode driver in a Docker container. To skip the installation of the +kernel-mode driver, proceed with the `--no-dkms` option, as shown below: + +```shell +sudo amdgpu-install --usecase=rocm --no-dkms +``` + +## Using the Installer Script for Multi-version ROCm Installation + +The multi-version ROCm installation requires you to download and install the +latest ROCm release installer from the list of ROCm releases you want to install +simultaneously on your system. + +**Example:** If you want to install ROCm releases 4.5.0, 4.5.1, and 5.4.3 +simultaneously, you are required to download the installer from the latest ROCm +release v5.4.3. + +To download and install the installer, refer to the [Download and Install the +Installer Script](#download-and-install-the-installer-script) section. + +```{attention} +If the existing ROCm release contains non-versioned ROCm packages, uninstall +those packages before proceeding with the multi-version installation to avoid +conflicts. +``` + +### Add Required ROCm Repositories + +Add the required repositories using the following steps: + +```{important} +Add the AMDGPU and ROCm repositories manually for all ROCm releases you want to +install except the latest one. The amdgpu-install script automatically adds the +required repositories for the latest release. +``` + +::::::{tab-set} +:::::{tab-item} Ubuntu +:sync: ubuntu + +::::{tab-set} +:::{tab-item} Ubuntu 20.04 +:sync: ubuntu-20.04 + +```shell +for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do +echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver focal main" | sudo tee /etc/apt/sources.list.d/rocm.list +done +echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 +sudo apt update +``` + +::: +:::{tab-item} Ubuntu 22.04 +:sync: ubuntu-22.04 + +```shell +for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do +echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" | sudo tee /etc/apt/sources.list.d/rocm.list +done +echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 +sudo apt update +``` + +::: +:::: +::::: +:::::{tab-item} Red Hat Enterprise Linux +:sync: RHEL + +```shell +for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do +sudo tee --append /etc/yum.repos.d/rocm.repo < +sudo amdgpu-install --usecase=rocm --rocmrelease= +sudo amdgpu-install --usecase=rocm --rocmrelease= +``` + +```{tip} +If the kernel-mode driver is already present on the system and you do not want +to upgrade it, use the `--no-dkms` option to skip the installation of the +kernel-mode driver, as shown in the following samples: +``` + +```none +sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.0 --no-dkms +sudo amdgpu-install --usecase=rocm --rocmrelease=5.4.3 --no-dkms +``` + +Following are examples of ROCm multi-version installation. The kernel-mode +driver, associated with the ROCm release v5.4.3, will be installed as its latest +release in the list. + +```none +sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.0 +sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.2 +sudo amdgpu-install --usecase=rocm --rocmrelease=5.4.3 +``` diff --git a/docs/deploy/linux/installer/uninstall.md b/docs/deploy/linux/installer/uninstall.md new file mode 100644 index 000000000..a16f82973 --- /dev/null +++ b/docs/deploy/linux/installer/uninstall.md @@ -0,0 +1,27 @@ +# Installer Script Uninstallation (Linux) + +::::{rubric} Uninstalling Single-Version Install +:::: + +```console shell +sudo amdgpu-install --uninstall +``` + +```{note} +This command uninstalls all ROCm packages associated with the installed ROCm +release along with the kernel-mode driver. +``` + +::::{rubric} Uninstalling a Specific ROCm Release +:::: + +```console shell +sudo amdgpu-install --uninstall --rocmrelease= +``` + +::::{rubric} Uninstalling all ROCm Releases +:::: + +```console shell +sudo amdgpu-install --uninstall --rocmrelease=all +``` diff --git a/docs/deploy/linux/installer/upgrade.md b/docs/deploy/linux/installer/upgrade.md new file mode 100644 index 000000000..783f13540 --- /dev/null +++ b/docs/deploy/linux/installer/upgrade.md @@ -0,0 +1,28 @@ +# Upgrading with the Installer Script (Linux) + +This section explains how to upgrade the existing kernel-mode driver and ROCm +packages to the latest version. The assumption is that you already have a +version of the kernel-mode driver and the ROCm software stack is installed on +the system. + +```{note} +Package upgrade is applicable to single-version packages only. If the preference +is to install an updated version of the ROCm stack along with the currently +installed version, refer to the [](install) page. +``` + +## Installer Script Method + +The installer script method automates the upgrade process for the AMDGPU and +ROCm stack. The `amdgpu-install` script handles the complete upgrade process for +ROCm, including updating the required repositories and upgrading the desired +meta-packages. + +The upgrade procedure is exactly the same as installing for 1st time use. Refer +to the {ref}`install-script-method` section on the exact procedure to follow. + +## Verification Process + +To verify if the upgrade is successful, refer to the +{ref}`post-install-actions-linux` given in the +[Installation](install) section. diff --git a/docs/deploy/linux/os-native/index.md b/docs/deploy/linux/os-native/index.md new file mode 100644 index 000000000..be2216111 --- /dev/null +++ b/docs/deploy/linux/os-native/index.md @@ -0,0 +1,38 @@ +# Distro Command Installation + +::::{grid} 2 3 3 3 +:gutter: 1 + +:::{grid-item-card} Install +:link: install +:link-type: doc + +How to install ROCm? +::: + +:::{grid-item-card} Upgrade +:link: upgrade +:link-type: doc + +Instructions for upgrading an existing ROCm installation. +::: + +:::{grid-item-card} Uninstall +:link: uninstall +:link-type: doc + +Steps for removing ROCm packages libraries and tools. +::: + +:::{grid-item-card} Package Manager Integration +:link: package_manager_integration +:link-type: doc + +Information about packages. +::: + +:::: + +## See Also + +- {doc}`/release/gpu_os_support` diff --git a/docs/deploy/linux/install.md b/docs/deploy/linux/os-native/install.md similarity index 57% rename from docs/deploy/linux/install.md rename to docs/deploy/linux/os-native/install.md index ae201e525..72b3d8fb2 100644 --- a/docs/deploy/linux/install.md +++ b/docs/deploy/linux/os-native/install.md @@ -1,396 +1,6 @@ # Installation (Linux) -Installing can be done in one of two ways, depending on your preference: - -- Using an installer script -- Through your system's package manager - -```{attention} -For information on installing ROCm on devices with NVIDIA GPUs, refer to the HIP -Installation Guide. -``` - -(install-script-method)= - -## Installer Script Method - -The installer script method automates the installation process for the AMDGPU -and ROCm stack. The installer script handles the complete installation process -for ROCm, including setting up the repository, cleaning the system, updating, -and installing the desired drivers and meta-packages. With this approach, the -system has more control over the ROCm installation process. Thus, those who are -less familiar with the Linux standard commands can choose this method for ROCm -installation. - -For AMDGPU and ROCm installation using the installer script method on Linux -distribution, follow these steps: - -1. **Meet prerequisites** – Ensure the Prerequisites are met before downloading - and installing the installer using the installer script method. - -2. **Download and install the installer script** – Ensure you download and - install the installer script from the recommended URL. - - ```{tip} - The installer package is updated periodically to resolve known issues and add - new features. The links for each Linux distribution always point to the latest - available build. - ``` - -3. **Use the installer script on Linux distributions** – Ensure you execute the - script for installing use cases. - -### Download and Install the Installer Script - -::::::{tab-set} -:::::{tab-item} Ubuntu -:sync: ubuntu - - -::::{rubric} To download the amdgpu-install script on the system, use the following commands. -:::: - -::::{tab-set} -:::{tab-item} Ubuntu 20.04 -:sync: ubuntu-20.04 - -```shell -sudo apt update -wget https://repo.radeon.com/amdgpu-install/5.4.3/ubuntu/focal/amdgpu-install_5.4.50403-1_all.deb -sudo apt install ./amdgpu-install_5.4.50403-1_all.deb -``` - -::: -:::{tab-item} Ubuntu 22.04 -:sync: ubuntu-22.04 - -```shell -sudo apt update -wget https://repo.radeon.com/amdgpu-install/5.4.3/ubuntu/jammy/amdgpu-install_5.4.50403-1_all.deb -sudo apt install ./amdgpu-install_5.4.50403-1_all.deb -``` - -::: -:::: -::::: -:::::{tab-item} Red Hat Enterprise Linux -:sync: RHEL - - -::::{rubric} To download the amdgpu-install script on the system, use the following commands. -:::: - -::::{tab-set} -:::{tab-item} RHEL 8.6 -:sync: RHEL-8.6 - -```shell -sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/8.6/amdgpu-install-5.4.50403-1.el8.noarch.rpm -``` - -::: -:::{tab-item} RHEL 8.7 -:sync: RHEL-8.7 - -```shell -sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/8.7/amdgpu-install-5.4.50403-1.el8.noarch.rpm -``` - -::: -:::{tab-item} RHEL 9.1 -:sync: RHEL-9.1 - -```shell -sudo yum install https://repo.radeon.com/amdgpu-install/5.4.3/rhel/9.1/amdgpu-install-5.4.50403-1.el9.noarch.rpm -``` - -::: -:::: -::::: -:::::{tab-item} SUSE Linux Enterprise Server 15 -:sync: SLES15 - - -::::{rubric} To download the amdgpu-install script on the system, use the following commands. -:::: - -::::{tab-set} -:::{tab-item} Service Pack 4 -:sync: SLES15-SP4 - -```shell -sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/5.4.3/sle/15.4/amdgpu-install-5.4.50403-1.noarch.rpm -``` - -::: -:::: -::::: -:::::: - -### Using the Installer Script for Single-version ROCm Installation - -To install use cases specific to your requirements, use the installer -`amdgpu-install` as follows: - -- To install a single use case: - - ```shell - sudo amdgpu-install --usecase=rocm - ``` - -- To install kernel-mode driver: - - ```shell - sudo amdgpu-install --usecase=dkms - ``` - -- To install multiple use cases: - - ```shell - sudo amdgpu-install --usecase=hiplibsdk,rocm - ``` - -- To display a list of available use cases: - - ```shell - sudo amdgpu-install --list-usecase - ``` - - Following is a sample of output listed by the command above: - - ```{note} - The list in this section represents only a sample of available use cases for ROCm: - ``` - - ```none - If --usecase option is not present, the default selection is "graphics,opencl,hip" - - Available use cases: - rocm(for users and developers requiring full ROCm stack) - - OpenCL (ROCr/KFD based) runtime - - HIP runtimes - - Machine learning framework - - All ROCm libraries and applications - - ROCm Compiler and device libraries - - ROCr runtime and thunk - lrt(for users of applications requiring ROCm runtime) - - ROCm Compiler and device libraries - - ROCr runtime and thunk - opencl(for users of applications requiring OpenCL on Vega or - later products) - - ROCr based OpenCL - - ROCm Language runtime - - openclsdk (for application developers requiring ROCr based OpenCL) - - ROCr based OpenCL - - ROCm Language runtime - - development and SDK files for ROCr based OpenCL - - hip(for users of HIP runtime on AMD products) - - HIP runtimes - hiplibsdk (for application developers requiring HIP on AMD products) - - HIP runtimes - - ROCm math libraries - - HIP development libraries - ``` - -```{tip} -Adding `-y` as a parameter to `amdgpu-install` skips user prompts (for -automation). Example: `amdgpu-install -y --usecase=rocm` -``` - -### Using Installer Script in Docker - -When the installation is initiated in Docker, the installer tries to install the -use case along with the kernel-mode driver. However, you cannot install the -kernel-mode driver in a Docker container. To skip the installation of the -kernel-mode driver, proceed with the `--no-dkms` option, as shown below: - -```shell -sudo amdgpu-install --usecase=rocm --no-dkms -``` - -### Using the Installer Script for Multi-version ROCm Installation - -The multi-version ROCm installation requires you to download and install the -latest ROCm release installer from the list of ROCm releases you want to install -simultaneously on your system. - -**Example:** If you want to install ROCm releases 4.5.0, 4.5.1, and 5.4.3 -simultaneously, you are required to download the installer from the latest ROCm -release v5.4.3. - -To download and install the installer, refer to the [Download and Install the -Installer Script](#download-and-install-the-installer-script) section. - -```{attention} -If the existing ROCm release contains non-versioned ROCm packages, uninstall -those packages before proceeding with the multi-version installation to avoid -conflicts. -``` - -#### Add Required ROCm Repositories - -Add the required repositories using the following steps: - -```{important} -Add the AMDGPU and ROCm repositories manually for all ROCm releases you want to -install except the latest one. The amdgpu-install script automatically adds the -required repositories for the latest release. -``` - -::::::{tab-set} -:::::{tab-item} Ubuntu -:sync: ubuntu - -::::{tab-set} -:::{tab-item} Ubuntu 20.04 -:sync: ubuntu-20.04 - -```shell -for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do -echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver focal main" | sudo tee /etc/apt/sources.list.d/rocm.list -done -echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 -sudo apt update -``` - -::: -:::{tab-item} Ubuntu 22.04 -:sync: ubuntu-22.04 - -```shell -for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do -echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" | sudo tee /etc/apt/sources.list.d/rocm.list -done -echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 -sudo apt update -``` - -::: -:::: -::::: -:::::{tab-item} Red Hat Enterprise Linux -:sync: RHEL - -```shell -for ver in 5.0.2 5.1.4 5.2.5 5.3.3; do -sudo tee --append /etc/yum.repos.d/rocm.repo < -sudo amdgpu-install --usecase=rocm --rocmrelease= -sudo amdgpu-install --usecase=rocm --rocmrelease= -``` - -```{tip} -If the kernel-mode driver is already present on the system and you do not want -to upgrade it, use the `--no-dkms` option to skip the installation of the -kernel-mode driver, as shown in the following samples: -``` - -```none -sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.0 --no-dkms -sudo amdgpu-install --usecase=rocm --rocmrelease=5.4.3 --no-dkms -``` - -Following are examples of ROCm multi-version installation. The kernel-mode -driver, associated with the ROCm release v5.4.3, will be installed as its latest -release in the list. - -```none -sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.0 -sudo amdgpu-install --usecase=rocm --rocmrelease=4.5.2 -sudo amdgpu-install --usecase=rocm --rocmrelease=5.4.3 -``` - -## Package Manager Method - -The package manager method involves a manual setup of the repository, which -includes setting up the repository, updating, and installing/uninstalling -meta-packages. This involves using standard commands such as yum, apt, and -others respective to the Linux distribution. - -The functions of a package manager installation system are: - -- Grouping packages based on function -- Extracting package archives -- Ensuring a package is installed with all necessary packages and dependencies - are managed -- From a remote repository, looking up, downloading, installing, or updating - existing packages -- Ensuring the authenticity and integrity of the package - -### Installing ROCm on Linux Distributions - -For a fresh ROCm installation using the package manager method on a Linux -distribution, follow the steps below: - -1. **Meet prerequisites** – Ensure the Prerequisites are met before the ROCm - installation. - -2. **Install kernel headers and development packages** – Ensure kernel headers - and development packages are installed on the system. - -3. **Select the base URLs for AMDGPU and ROCm stack repository** – Ensure the - base URLs for AMDGPU and ROCm stack repositories are selected. - -4. **Add the AMDGPU stack repository** – Ensure the AMDGPU stack repository is - added. - -5. **Install the kernel-mode driver and reboot the system** – Ensure the - kernel-mode driver is installed and the system is rebooted. - -6. **Add ROCm stack repository** – Ensure the ROCm stack repository is added. - -7. **Install single-version or multi-version ROCm meta-packages** – Install the - desired meta-packages. - -8. **Verify installation for the applicable distributions** – Verify if the - installation is successful. - -```{important} -You cannot install a kernel-mode driver in a Docker container. Refer to the -sections below for specific commands to install the AMDGPU and ROCm stack on -various Linux distributions. -``` - -#### Understanding the Release-specific AMDGPU and ROCm Stack Repositories on Linux Distributions +## Understanding the Release-specific AMDGPU and ROCm Stack Repositories on Linux Distributions The release-specific repositories consist of packages from a specific release of the AMDGPU stack and ROCm stack. The repositories are not updated for the latest @@ -400,15 +10,13 @@ release to install, update the previously installed single version to the later available release, or add the latest version of ROCm along with the currently installed version by using the multi-version ROCm packages. +## Step by Step Instructions + ```{note} Users installing multiple versions of the ROCm stack must use the -release-specific base URL. +release-specific repository URL. ``` -(using-the-package-manager)= - -#### Using the Package Manager - ::::::{tab-set} :::::{tab-item} Ubuntu :sync: ubuntu @@ -532,7 +140,7 @@ follow these steps: :sync: ubuntu-20.04 ```shell - for ver in 5.0.2 5.1.4 5.2.5 5.3.3 5.4.3; do + for ver in 5.3.3 5.4.3; do echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver focal main" | sudo tee /etc/apt/sources.list.d/rocm.list done echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 @@ -544,8 +152,8 @@ follow these steps: :sync: ubuntu-22.04 ```shell - for ver in 5.0.2 5.1.4 5.2.5 5.3.3 5.4.3; do - echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" | sudo tee /etc/apt/sources.list.d/rocm.list + for ver in 5.5.1 5.4.3 5.3.3 ; do + echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" | sudo tee --append /etc/apt/sources.list.d/rocm.list done echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600 sudo apt update @@ -575,7 +183,7 @@ follow these steps: ``` ```shell - sudo apt install rocm-hip-sdk5.4.3 rocm-hip-sdk5.2.5 + sudo apt install rocm-hip-sdk5.4.3 rocm-hip-sdk5.3.3 ``` ::::: @@ -677,7 +285,7 @@ follow these steps: sudo tee --append /etc/yum.repos.d/amdgpu.repo </` + +For example, you can fetch the licensing information of the `_amd_comgr_` +component (Code Object Manager) from the `amd_comgr` folder. A file named +`LICENSE.txt` contains the license details at: +`/opt/rocm-5.4.3/share/doc/amd_comgr/LICENSE.txt` diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index e0577f882..b0c1e996d 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -19,13 +19,24 @@ subtrees: title: Installation Overview - file: deploy/linux/prerequisites title: Prerequisites - - file: deploy/linux/install - title: Installation - - file: deploy/linux/upgrade - title: Upgrade - - file: deploy/linux/uninstall - title: Uninstallation - - file: deploy/linux/package_manager_integration + - file: deploy/linux/os-native/index + subtrees: + - entries: + - file: deploy/linux/os-native/install + title: Installation + - file: deploy/linux/os-native/upgrade + title: Upgrade + - file: deploy/linux/os-native/uninstall + title: Uninstallation + - file: deploy/linux/os-native/package_manager_integration + - file: deploy/linux/installer/index + subtrees: + - entries: + - file: deploy/linux/installer/install + title: Installation + - file: deploy/linux/installer/upgrade + title: Upgrade + - file: deploy/linux/installer/uninstall - file: deploy/docker title: Docker