diff --git a/docs/deploy/linux/index.md b/docs/deploy/linux/index.md index 13f4275b1..49080b0d5 100644 --- a/docs/deploy/linux/index.md +++ b/docs/deploy/linux/index.md @@ -19,7 +19,7 @@ The prerequisites page lists the required steps *before* installation. :link: install_overview :link-type: doc -Distro Commands vs AMDGPU Installer +Package manager vs AMDGPU Installer Standard Packages vs Multi-Version Packages ::: @@ -31,7 +31,7 @@ Standard Packages vs Multi-Version Packages ::::{grid} 1 1 2 2 :gutter: 1 -:::{grid-item-card} Distro Commands +:::{grid-item-card} Package Manager :link: os-native/index :link-type: doc diff --git a/docs/deploy/linux/install_overview.md b/docs/deploy/linux/install_overview.md index baf865f99..17d243074 100644 --- a/docs/deploy/linux/install_overview.md +++ b/docs/deploy/linux/install_overview.md @@ -3,22 +3,30 @@ Users installing ROCm must choose between various installation options. A new user should follow the [Quick Start guide](./quick_start). -## Distro Package Manager Commands versus AMDGPU Installer? +## Package Manager versus AMDGPU Installer? -Users can install the same packages via two CLI interfaces as follows: +ROCm supports two methods for installation: -- Linux distro package manager commands. -- a proprietary installer known as the `amdgpu-install` script +- Directly using the Linux distribution's package manager +- The `amdgpu-install` script -There is no difference in the final installation state when choosing either CLI. +There is no difference in the final installation state when choosing either +option. -Integrating with the distribution's package manager lets the user install, +Using 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. The `amdgpu-install` script is a wrapper around the package manager. The same packages are installed by this script as the package manager system. +The installer automates the installation process for the AMDGPU +and ROCm stack. It 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 package manager can choose this method for ROCm +installation. + (installation-types)= ## Single Version ROCm install versus Multi-Version diff --git a/docs/deploy/linux/installer/install.md b/docs/deploy/linux/installer/install.md index bb85ba875..9229d28e7 100644 --- a/docs/deploy/linux/installer/install.md +++ b/docs/deploy/linux/installer/install.md @@ -1,27 +1,17 @@ -# 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. +# Installation with install script Prior to beginning, please ensure you have the [prerequisites](../prerequisites) installed. -## Download and Install the Installer Script +## Download the Installer Script + +To download and install the `amdgpu-install` script on the system, use the +following commands based on your distribution. ::::::{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 @@ -48,10 +38,6 @@ sudo apt install ./amdgpu-install_5.5.50501-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 @@ -98,10 +84,6 @@ sudo yum install https://repo.radeon.com/amdgpu-install/5.5.1/rhel/9.2/amdgpu-in :::::{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 @@ -115,117 +97,94 @@ sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/5.5.1 ::::: :::::: -## Using the Installer Script for Single-version ROCm Installation +## Use cases + +Instead of installing individual applications or libraries the installer script +groups packages into specific use cases, matching typical workflows and runtimes. + +To display a list of available use cases execute the command: + +```shell +sudo amdgpu-install --list-usecase +``` + +The available use-cases will be printed in a format similar to the example +output below. + +```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 +``` To install use cases specific to your requirements, use the installer `amdgpu-install` as follows: -- To install a single use case: +- To install a single use case add it with the `--usecase` option: ```shell sudo amdgpu-install --usecase=rocm ``` -- To install kernel-mode driver: - - ```shell - sudo amdgpu-install --usecase=dkms - ``` - -- To install multiple use cases: +- For multiple use cases separate them with commas: ```shell sudo amdgpu-install --usecase=hiplibsdk,rocm ``` -- To display a list of available use cases: +## Single-version ROCm Installation - ```shell - sudo amdgpu-install --list-usecase - ``` +By default (without the `--rocmrelease` option) +the installer script will install packages in the single-version layout. - Following is a sample of output listed by the command above: +## Multi-version ROCm Installation - ```{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. +For the multi-version ROCm installation you must use the installer script from +the latest release of ROCm that you wish to install. **Example:** If you want to install ROCm releases 5.3.3 and 5.5.1 simultaneously, you are required to download the installer from the latest ROCm release v5.5.1. -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 +ROCm packages that were previously installed from a single-version installation +must be removed before proceeding with the multi-version installation to avoid conflicts. ``` -### Add Required ROCm Repositories +### Add Required Repositories -Add the required repositories using the following steps: +You must add the 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. -```{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. -``` +Run the following commands based on your distribution to add the repositories: ::::::{tab-set} :::::{tab-item} Ubuntu @@ -236,7 +195,7 @@ required repositories for the latest release. :sync: ubuntu-20.04 ```shell -for ver in 5.3.3 5.5.1; 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 @@ -248,7 +207,7 @@ sudo apt update :sync: ubuntu-22.04 ```shell -for ver in 5.3.3 5.5.1; 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 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 @@ -262,7 +221,7 @@ sudo apt update :sync: RHEL ```shell -for ver in 5.3.3 5.5.1; do +for ver in 5.3.3 5.4.3; do sudo tee --append /etc/yum.repos.d/rocm.repo < 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=5.3.3 --no-dkms -sudo amdgpu-install --usecase=rocm --rocmrelease=5.5.1 --no-dkms -``` - Following are examples of ROCm multi-version installation. The kernel-mode driver, associated with the ROCm release v5.5.1, will be installed as its latest release in the list. @@ -325,3 +273,21 @@ release in the list. sudo amdgpu-install --usecase=rocm --rocmrelease=5.3.3 sudo amdgpu-install --usecase=rocm --rocmrelease=5.5.1 ``` + +## Additional options + +### Unattended installation + +Adding `-y` as a parameter to `amdgpu-install` skips user prompts (for +automation). Example: `amdgpu-install -y --usecase=rocm` + +### Skipping kernel mode driver installation + +The installer script tries to install the kernel mode driver along with the +requested use cases. This might be unnecessary as in the case of docker +containers or you may wish to keep a specific version when using multi-version +installation, and not have the last installed version overwrite the kernel mode +driver. + +To skip the installation of the kernel-mode driver add the `--no-dkms` option +when calling the installer script. diff --git a/docs/deploy/linux/installer/uninstall.md b/docs/deploy/linux/installer/uninstall.md index a16f82973..cb5887ba7 100644 --- a/docs/deploy/linux/installer/uninstall.md +++ b/docs/deploy/linux/installer/uninstall.md @@ -1,5 +1,8 @@ # Installer Script Uninstallation (Linux) +To uninstall all ROCm packages and the kernel-mode driver the following commands +can be used. + ::::{rubric} Uninstalling Single-Version Install :::: @@ -7,11 +10,6 @@ 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 :::: diff --git a/docs/deploy/linux/installer/upgrade.md b/docs/deploy/linux/installer/upgrade.md index 783f13540..6a193cd17 100644 --- a/docs/deploy/linux/installer/upgrade.md +++ b/docs/deploy/linux/installer/upgrade.md @@ -1,28 +1,5 @@ # 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. +The upgrade procedure with the installer script is exactly the same as +installing for 1st time use. Refer to the {doc}`install` +section on the exact procedure to follow. diff --git a/docs/deploy/linux/os-native/index.md b/docs/deploy/linux/os-native/index.md index be2216111..e65e3aa21 100644 --- a/docs/deploy/linux/os-native/index.md +++ b/docs/deploy/linux/os-native/index.md @@ -1,4 +1,4 @@ -# Distro Command Installation +# Installation via Package manager ::::{grid} 2 3 3 3 :gutter: 1 diff --git a/docs/deploy/linux/os-native/uninstall.md b/docs/deploy/linux/os-native/uninstall.md index 027d7914f..6be41ed26 100644 --- a/docs/deploy/linux/os-native/uninstall.md +++ b/docs/deploy/linux/os-native/uninstall.md @@ -1,23 +1,9 @@ -# Uninstallation (Linux) +# Uninstallation with package manager (Linux) -Uninstallation of ROCm entails removing ROCm packages, tools, and libraries from -the system. - -You can uninstall using the following methods: - -- Package manager uninstallation -- Uninstallation using the uninstall script - -```{attention} -Use the same uninstall method that you used to install ROCm. Mixing procedures -is untested and may result in inconsistent system state. -``` - -## Package Manager Method - -The package manager uninstallation offers a method for a clean uninstallation -process for ROCm. This section describes how to uninstall the ROCm instance from -various Linux distributions. +This section describes how to uninstall ROCm with the Linux distribution's +package manager. This method should be used if ROCm was installed via the package +manager. If the installer script was used for installation, then it should be +used for uninstallation too, refer to {doc}`/deploy/linux/installer/uninstall`. ::::::{tab-set} :::::{tab-item} Ubuntu @@ -182,31 +168,3 @@ sudo zypper remove --clean-deps amdgpu-dkms ::::: :::::: - -## Installer Script Method - -::::{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/os-native/upgrade.md b/docs/deploy/linux/os-native/upgrade.md index 82cc0ab91..6f71d36b2 100644 --- a/docs/deploy/linux/os-native/upgrade.md +++ b/docs/deploy/linux/os-native/upgrade.md @@ -1,4 +1,4 @@ -# Upgrade ROCm with Linux Distribution Commands +# Upgrade ROCm with the package manager This section explains how to upgrade the existing AMDGPU driver and ROCm packages to the latest version using your OS's distributed package manager. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index b0c1e996d..61128b69f 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -37,6 +37,7 @@ subtrees: - file: deploy/linux/installer/upgrade title: Upgrade - file: deploy/linux/installer/uninstall + title: Uninstallation - file: deploy/docker title: Docker