diff --git a/docs/conf.py b/docs/conf.py index cfec670f..601117d5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ sles_version_numbers = ['15.5', '15.4'] ol_release_version_numbers = ['8'] ol_version_numbers = [('8', '8.8')] +ubuntu_wsl2_docker_desktop_win_version_numbers = [('22.04', 'jammy')] # pages with specific settings article_pages = [ @@ -85,5 +86,6 @@ "rhel_release_version_numbers" : rhel_release_version_numbers, "rhel_version_numbers" : rhel_version_numbers, "ol_release_version_numbers" : ol_release_version_numbers, - "ol_version_numbers" : ol_version_numbers + "ol_version_numbers" : ol_version_numbers, + "ubuntu_wsl2_docker_desktop_win_version_numbers": ubuntu_wsl2_docker_desktop_win_version_numbers } diff --git a/docs/how-to/amdgpu-install.rst b/docs/how-to/amdgpu-install.rst index 54288d4e..588e989c 100644 --- a/docs/how-to/amdgpu-install.rst +++ b/docs/how-to/amdgpu-install.rst @@ -31,7 +31,7 @@ Ubuntu .. tab-set:: {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} - .. tab-item:: Ubuntu {{ os_version }} + .. tab-item:: {{ os_version }} :sync: ubuntu-{{ os_version}} .. code-block:: bash @@ -49,7 +49,7 @@ Red Hat Enterprise Linux .. tab-set:: {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} - .. tab-item:: RHEL {{ os_version }} + .. tab-item:: {{ os_version }} :sync: rhel-{{ os_version }} rhel-{{ os_release }} .. code-block:: bash @@ -65,7 +65,7 @@ Oracle Linux .. tab-set:: {% for (os_release, os_version) in config.html_context['ol_version_numbers'] %} - .. tab-item:: OL {{ os_version }} + .. tab-item:: {{ os_version }} :sync: ol-{{ os_version }} ol-{{ os_release }} .. code-block:: bash @@ -82,7 +82,7 @@ SUSE Linux Enterprise .. tab-set:: {% for os_version in config.html_context['sles_version_numbers'] %} - .. tab-item:: SLES {{ os_version }} + .. tab-item:: {{ os_version }} .. code-block:: bash :substitutions: @@ -90,6 +90,24 @@ SUSE Linux Enterprise sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm {% endfor %} +Ubuntu (WSL2 / Docker for Windows) +-------------------------------------------------------------------- + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_wsl2_docker_desktop_win_version_numbers'] %} + .. tab-item:: {{ os_version }} + :sync: ubuntu-wsl2-docker-desktop-win-{{ os_version}} + + .. code-block:: bash + :substitutions: + + sudo apt update + wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb + {% endfor %} + Use cases ================================================= @@ -128,6 +146,8 @@ output below. - HIP runtimes - Machine learning framework - All ROCm libraries and applications + wsl (for using ROCm in a WSL) + - ROCr WSL runtime library (Ubuntu 22.04 only) rocmdev (for developers requiring ROCm runtime and profiling/debugging tools) - HIP runtimes @@ -216,6 +236,13 @@ To install use cases specific to your requirements, use the installer sudo amdgpu-install --usecase=rocm,asan +- To install the WSL2 and Docker Desktop for Windows compatible binaries add + ``wsl``. For example: + + .. code-block:: bash + + sudo amdgpu-install --usecase=rocm,wsl --no-dkms --no-32 + Uninstalling ROCm ================================================= diff --git a/docs/how-to/docker.rst b/docs/how-to/docker.rst index 366860c7..c198bf0c 100644 --- a/docs/how-to/docker.rst +++ b/docs/how-to/docker.rst @@ -15,54 +15,78 @@ ROCm kernel-mode driver must be installed on the host. Please refer to user-space parts (like the HIP-runtime or math libraries) of the ROCm stack will be loaded from the container image and don't need to be installed to the host. +Linux Docker containers running on Windows do not make use of ``amdgpu-dkms``, +but instead use an alternative user-space ROCm Runtime (ROCr) relaying to the +host driver. + .. _docker-access-gpus-in-container: Accessing GPUs in containers ========================================== -In order to access GPUs in a container (to run applications using HIP, OpenCL or -OpenMP offloading) explicit access to the GPUs must be granted. +.. tab-set:: -The ROCm runtimes make use of multiple device files: + .. tab-item:: Native Linux + :sync: native-linux-tab -- ``/dev/kfd``: the main compute interface shared by all GPUs -- ``/dev/dri/renderD``: direct rendering interface (DRI) devices for each - GPU. Where ```` is a number for each card in the system starting from 128. + In order to access GPUs in a container (to run applications using HIP, OpenCL or + OpenMP offloading) explicit access to the GPUs must be granted. -Exposing these devices to a container is done by using the -`--device `_ -option, i.e. to allow access to all GPUs expose ``/dev/kfd`` and all -``/dev/dri/renderD`` devices: + The ROCm runtimes make use of multiple device files: -.. code-block:: shell + - ``/dev/kfd``: the main compute interface shared by all GPUs + - ``/dev/dri/renderD``: direct rendering interface (DRI) devices for each + GPU. Where ```` is a number for each card in the system starting from 128. - docker run --device /dev/kfd --device /dev/renderD128 --device /dev/renderD129 ... + Exposing these devices to a container is done by using the + `--device `_ + option, i.e. to allow access to all GPUs expose ``/dev/kfd`` and all + ``/dev/dri/renderD`` devices: -More conveniently, instead of listing all devices, the entire ``/dev/dri`` folder -can be exposed to the new container: + .. code-block:: shell -.. code-block:: shell + docker run --device /dev/kfd --device /dev/renderD128 --device /dev/renderD129 ... + + More conveniently, instead of listing all devices, the entire ``/dev/dri`` folder + can be exposed to the new container: + + .. code-block:: shell + + docker run --device /dev/kfd --device /dev/dri - docker run --device /dev/kfd --device /dev/dri + Note that this gives more access than strictly required, as it also exposes the + other device files found in that folder to the container. -Note that this gives more access than strictly required, as it also exposes the -other device files found in that folder to the container. + .. tab-item:: WSL2 / Docker Desktop for Windows + :sync: wsl2-docker-desktop-win-tab + + GPUs are automatically available to ROCr on WSL2 kernels and need no user intervention. .. _docker-restrict-gpus: Restricting a container to a subset of the GPUs ------------------------------------------------------------------------------------------------- -If a ``/dev/dri/renderD`` device is not exposed to a container then it cannot use -the GPU associated with it; this allows to restrict a container to any subset of -devices. +.. tab-set:: -For example to allow the container to access the first and third GPU start it -like: + .. tab-item:: Native Linux + :sync: native-linux-tab -.. code-block:: shell + If a ``/dev/dri/renderD`` device is not exposed to a container then it cannot use + the GPU associated with it; this allows to restrict a container to any subset of + devices. + + For example to allow the container to access the first and third GPU start it + like: + + .. code-block:: shell + + docker run --device /dev/kfd --device /dev/dri/renderD128 --device /dev/dri/renderD130 + + .. tab-item:: WSL2 / Docker Desktop for Windows + :sync: wsl2-docker-desktop-win-tab - docker run --device /dev/kfd --device /dev/dri/renderD128 --device /dev/dri/renderD130 + Devices can't be filtered at the hypervisor level. Additional options ------------------------------------------------------------------------------------------------- diff --git a/docs/how-to/native-install/index.rst b/docs/how-to/native-install/index.rst index 406bd8ea..ea1caa2e 100644 --- a/docs/how-to/native-install/index.rst +++ b/docs/how-to/native-install/index.rst @@ -15,6 +15,8 @@ Installation via native package manager - :doc:`Ubuntu` - :doc:`Red Hat Enterprise Linux` - :doc:`SUSE Linux Enterprise` + - :doc:`Oracle Linux` + - :doc:`Ubuntu (WSL2 / Docker Desktop for Windows)` .. grid-item-card:: Upgrade diff --git a/docs/how-to/native-install/ol.rst b/docs/how-to/native-install/ol.rst index 53e709a0..62c631c4 100644 --- a/docs/how-to/native-install/ol.rst +++ b/docs/how-to/native-install/ol.rst @@ -19,7 +19,7 @@ Register kernel-mode driver .. tab-set:: {% for (os_release, os_version) in config.html_context['ol_version_numbers'] %} - .. tab-item:: OL {{ os_version }} + .. tab-item:: {{ os_version }} :sync: ol-{{ os_version }} ol-{{ os_release }} .. code-block:: bash @@ -46,7 +46,7 @@ Register ROCm packages .. tab-set:: {% for os_release in config.html_context['ol_release_version_numbers'] %} - .. tab-item:: OL {{ os_release }} + .. tab-item:: {{ os_release }} :sync: ol-{{ os_release }} .. code-block:: bash diff --git a/docs/how-to/native-install/post-install.rst b/docs/how-to/native-install/post-install.rst index 4b053b1b..1c8a70d8 100644 --- a/docs/how-to/native-install/post-install.rst +++ b/docs/how-to/native-install/post-install.rst @@ -62,3 +62,9 @@ Post-installation instructions .. code-block:: bash sudo zypper search --installed-only + + .. tab-item:: Ubuntu (WSL2 / Docker for Windows) + + .. code-block:: bash + + sudo apt list --installed diff --git a/docs/how-to/native-install/rhel.rst b/docs/how-to/native-install/rhel.rst index bfd077ff..186968f3 100644 --- a/docs/how-to/native-install/rhel.rst +++ b/docs/how-to/native-install/rhel.rst @@ -19,7 +19,7 @@ Register kernel-mode driver .. tab-set:: {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} - .. tab-item:: RHEL {{ os_version }} + .. tab-item:: {{ os_version }} :sync: rhel-{{ os_version }} rhel-{{ os_release }} .. code-block:: bash @@ -46,7 +46,7 @@ Register ROCm packages .. tab-set:: {% for os_release in config.html_context['rhel_release_version_numbers'] %} - .. tab-item:: RHEL {{ os_release }} + .. tab-item:: {{ os_release }} :sync: rhel-{{ os_release }} .. code-block:: bash diff --git a/docs/how-to/native-install/sles.rst b/docs/how-to/native-install/sles.rst index 47f6bb37..c70331ee 100644 --- a/docs/how-to/native-install/sles.rst +++ b/docs/how-to/native-install/sles.rst @@ -20,7 +20,7 @@ Register kernel-mode driver .. tab-set:: {% for os_version in config.html_context['sles_version_numbers'] %} - .. tab-item:: SLES {{ os_version }} + .. tab-item:: {{ os_version }} .. code-block:: bash :substitutions: diff --git a/docs/how-to/native-install/ubuntu-wsl2-docker-desktop-win.rst b/docs/how-to/native-install/ubuntu-wsl2-docker-desktop-win.rst new file mode 100644 index 00000000..93b6f694 --- /dev/null +++ b/docs/how-to/native-install/ubuntu-wsl2-docker-desktop-win.rst @@ -0,0 +1,155 @@ +.. meta:: + :description: Ubuntu (WSL2 / Docker for Windows) installation + :keywords: ROCm install, installation instructions, Ubuntu, + Ubuntu (WSL2 / Docker for Windows) installation, AMD, ROCm, WSL, + Docker, Docker Desktop for Windows + +**************************************************************************** +Ubuntu (WSL2 / Docker for Windows) installation +**************************************************************************** + +.. _ubuntu-wsl2-docker-desktop-win-register-repo: + +Registering repositories +================================================= + +Package signing key +--------------------------------------------------------------------------- + +Download and convert the package signing key. + +.. code-block:: bash + + # Make the directory if it doesn't exist yet. + # This location is recommended by the distribution maintainers. + sudo mkdir --parents --mode=0755 /etc/apt/keyrings + + # Download the key, convert the signing-key to a full + # keyring required by apt and store in the keyring directory + wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \ + gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null + +.. _ubuntu-wsl2-docker-desktop-win-register-driver: + +.. note:: + The GPG key may change; ensure it is updated when installing a new release. + If the key signature verification fails while updating, + re-add the key from the ROCm to the apt repository as mentioned above. + The current ``rocm.gpg.key`` is not available in a standard key ring distribution + but has the following SHA1 sum hash: + ``73f5d8100de6048aa38a8b84cd9a87f05177d208 rocm.gpg.key`` + +Register ROCm packages +--------------------------------------------------------------------------- + +Add the ROCm repository. + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_wsl2_docker_desktop_win_version_numbers'] %} + .. tab-item:: {{ os_version }} + :sync: ubuntu-wsl2-docker-desktop-win-{{ os_version}} + + .. code-block:: bash + :substitutions: + + echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/|rocm_version| {{ os_release }} main" \ + | sudo tee --append /etc/apt/sources.list.d/rocm.list + echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' \ + | sudo tee /etc/apt/preferences.d/rocm-pin-600 + {% endfor %} + +.. _ubuntu-wsl2-docker-desktop-win-install: + +Installing +================================================ + +Install override packages +--------------------------------------------------------------------------- + +Linux Docker containers running on Windows do not make use of ``amdgpu-dkms``, +but instead use an alternative user-space ROCm Runtime (ROCr) relaying to the +host driver. + +The following packages override the native packages. + +.. code-block:: bash + + sudo apt install hsa-runtime-rocr4wsl-amdgpu rocminfo4wsl-amdgpu + sudo reboot + +Install ROCm packages +--------------------------------------------------------------------------- + +.. code-block:: bash + + sudo apt install rocm + +Complete the :doc:`post-install`. + +.. _ubuntu-wsl2-docker-desktop-win-upgrade: + +Upgrading +================================================ + +To upgrade an existing ROCm installation to a newer version, follow the steps in +:ref:`ubuntu-register-repo` and :ref:`ubuntu-install`. + +.. note:: + + Upgrading the kernel driver may also upgrade the GPU firmware, which requires a + system reboot to take effect. + +.. _ubuntu-wsl2-docker-desktop-win-uninstall: + +Uninstalling +================================================ + +Uninstall specific meta packages +--------------------------------------------------------------------------- + +.. code-block:: bash + :substitutions: + + # sudo apt autoremove + # For example: + sudo apt autoremove rocm + # Or for version specific packages: + sudo apt autoremove rocm|rocm_version| + +Uninstall ROCm packages +--------------------------------------------------------------------------- + +.. code-block:: bash + :substitutions: + + sudo apt autoremove rocm-core + # Or for version specific packages: + sudo apt autoremove rocm-core|rocm_version| + +Uninstall override packages +--------------------------------------------------------------------------- + +Although WSL2 and Docker Desktop for Windows installs don't need to uninstall +the DKMS driver, the override packages were manually installed and won't be +removed by uninstalling ``rocm-core``. + +.. code-block:: bash + + sudo apt autoremove hsa-runtime-rocr4wsl-amdgpu rocminfo4wsl-amdgpu + +Remove ROCm and AMDGPU repositories +--------------------------------------------------------------------------- + +.. code-block:: bash + + # Remove the repositories. + sudo rm /etc/apt/sources.list.d/rocm.list + + # Clear the cache and clean the system. + sudo rm -rf /var/cache/apt/* + sudo apt-get clean all + + # Restart the system. + sudo reboot diff --git a/docs/how-to/native-install/ubuntu.rst b/docs/how-to/native-install/ubuntu.rst index 393d60bf..cb73f728 100644 --- a/docs/how-to/native-install/ubuntu.rst +++ b/docs/how-to/native-install/ubuntu.rst @@ -46,7 +46,7 @@ Add the AMDGPU repository for the driver. .. tab-set:: {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} - .. tab-item:: Ubuntu {{ os_version }} + .. tab-item:: {{ os_version }} :sync: ubuntu-{{ os_version}} .. code-block:: bash @@ -68,7 +68,7 @@ Add the ROCm repository. .. tab-set:: {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} - .. tab-item:: Ubuntu {{ os_version }} + .. tab-item:: {{ os_version }} :sync: ubuntu-{{ os_version}} .. code-block:: bash diff --git a/docs/how-to/prerequisites.rst b/docs/how-to/prerequisites.rst index 947156f2..f60716a1 100644 --- a/docs/how-to/prerequisites.rst +++ b/docs/how-to/prerequisites.rst @@ -108,6 +108,11 @@ installation. Follow the instructions below based on your distributions. {% endfor %} + .. tab-item:: Ubuntu (WSL2 / Docker Desktop for Windows) + :sync: ubuntu-wsl2-docker-desktop-win-tab + + All packages are available in the default Ubuntu repositories, therefore no additional repositories need to be added. + Kernel headers and development packages ================================================================ @@ -144,6 +149,11 @@ To install for the currently active kernel run the command corresponding to your sudo zypper install kernel-default-devel + .. tab-item:: Ubuntu (WSL2 / Docker Desktop for Windows) + :sync: ubuntu-wsl2-docker-desktop-win-tab + + WSL2 and Docker for Windows don't make use of DKMS, instead they rely on an alternative ROCr (ROCm Runtime) binary relaying to the host driver. + Setting permissions for groups ================================================================ @@ -172,3 +182,11 @@ the following commands: echo 'ADD_EXTRA_GROUPS=1' | sudo tee -a /etc/adduser.conf echo 'EXTRA_GROUPS=video' | sudo tee -a /etc/adduser.conf echo 'EXTRA_GROUPS=render' | sudo tee -a /etc/adduser.conf + +Host system requirements +================================================================ + +When installing ROCm in WSL2 or Docker Desktop for Windows containers, the host +system must have the latest device drivers installed on the host system. To +obtain the latest drivers for your system, visit +`AMD Drivers and Support `_. diff --git a/docs/reference/system-requirements.rst b/docs/reference/system-requirements.rst index 33b999db..a9b04d73 100644 --- a/docs/reference/system-requirements.rst +++ b/docs/reference/system-requirements.rst @@ -87,9 +87,14 @@ AMD ROCmβ„’ Software supports the following Linux distributions. "Ubuntu 22.04.2", "5.19", "βœ…" "Ubuntu 20.04.6", "5.15", "βœ…" "Ubuntu 20.04.5", "5.15", "βœ…" + "Ubuntu 22.04.3", "5.15.133.1-microsoft-standard-WSL2", "🚧 :sup:`3`" + +🚧: **Preview** - This configuration is under development and is released for preview purposes. :sup:`2` Preview support for HWE kernels +:sup:`3` Preview support for device access in WSL2 and Docker Desktop for Windows. + Virtualization support ============================================= diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index f4208c22..69b736f9 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -26,6 +26,8 @@ subtrees: title: Oracle Linux - file: how-to/native-install/sles title: SUSE Linux Enterprise + - file: how-to/native-install/ubuntu-wsl2-docker-desktop-win + title: WSL2 & Docker Desktop for Windows - file: how-to/native-install/post-install title: Post-Install instructions - file: how-to/native-install/package-manager-integration diff --git a/docs/tutorial/quick-start.rst b/docs/tutorial/quick-start.rst index 4c5ffd9e..72eae615 100644 --- a/docs/tutorial/quick-start.rst +++ b/docs/tutorial/quick-start.rst @@ -22,12 +22,16 @@ To start, choose your preferred install method and operating system: * :ref:`package-man-ubuntu` * :ref:`package-man-rhel` * :ref:`package-man-suse` + * :ref:`package-man-ol` + * :ref:`package-man-ubuntu-wsl2-docker-desktop-win` .. grid-item-card:: :ref:`rocm-amdgpu-quick` * :ref:`amdgpu-ubuntu` * :ref:`amdgpu-rhel` * :ref:`amdgpu-suse` + * :ref:`amdgpu-ol` + * :ref:`amdgpu-ubuntu-wsl2-docker-desktop-win` .. _rocm-package-man-quick: @@ -143,6 +147,28 @@ SUSE Linux Enterprise Server echo "Please reboot system for all settings to take effect." {% endfor %} +.. _package-man-ubuntu-wsl2-docker-desktop-win: + +Ubuntu (WSL2 / Docker for Windows) +------------------------------------------------------------------------------------ + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_wsl2_docker_desktop_win_version_numbers'] %} + .. tab-item:: {{ os_version }} + :sync: ubuntu-wsl2-docker-desktop-win-{{ os_version}} + + .. code-block:: bash + :substitutions: + + wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt update + sudo apt install hsa-runtime-rocr4wsl-amdgpu rocminfo4wsl-amdgpu + sudo apt install rocm + {% endfor %} + .. _rocm-amdgpu-quick: AMDGPU installer @@ -225,3 +251,24 @@ SUSE Linux Enterprise Server sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm sudo amdgpu-install --usecase=graphics,rocm {% endfor %} + +.. _amdgpu-ubuntu-wsl2-docker-desktop-win: + +Ubuntu (WSL2 / Docker for Windows) +------------------------------------------------------------------------------------ + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_wsl2_docker_desktop_win_version_numbers'] %} + .. tab-item:: {{ os_version }} + :sync: ubuntu-wsl2-docker-desktop-win-{{ os_version}} + + .. code-block:: bash + :substitutions: + + sudo apt update + wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb + sudo amdgpu-install --usecase=graphics,rocm,wsl + {% endfor %}