From 8bc0138802a4820cc35cc3671a4016bdc1010666 Mon Sep 17 00:00:00 2001 From: spolifroni-amd Date: Tue, 14 Jan 2025 14:37:24 -0500 Subject: [PATCH] Created a more comprehensive installation from the readme information --- docs/conf.py | 1 + docs/index.rst | 19 +- docs/install/install.rst | 192 ------------------ docs/install/rpp-build-and-install.rst | 52 +++++ docs/install/rpp-install-with-installer.rst | 67 ++++++ docs/install/rpp-install.rst | 15 ++ docs/install/rpp-prerequisites.rst | 32 +++ docs/install/rpp-verify-install.rst | 50 +++++ .../rpp-supported-functionalities.rst} | 39 +--- docs/sphinx/_toc.yml.in | 15 +- 10 files changed, 239 insertions(+), 243 deletions(-) delete mode 100644 docs/install/install.rst create mode 100644 docs/install/rpp-build-and-install.rst create mode 100644 docs/install/rpp-install-with-installer.rst create mode 100644 docs/install/rpp-install.rst create mode 100644 docs/install/rpp-prerequisites.rst create mode 100644 docs/install/rpp-verify-install.rst rename docs/{what-is-rpp.rst => reference/rpp-supported-functionalities.rst} (78%) diff --git a/docs/conf.py b/docs/conf.py index 71cdb936d..111f1d8db 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,6 +56,7 @@ docs_core.myst_heading_anchors = 6 external_projects_current_project = "rpp" +external_projects_remote_repository="" for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/index.rst b/docs/index.rst index cefda18fb..154b36838 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,30 +6,31 @@ ROCm Performance Primitives documentation ******************************************************************** -AMD ROCm Performance Primitives (RPP) is a comprehensive, high-performance computer vision -library for AMD processors that have HIP, OpenCL, or CPU backends. For more information, refer to -:doc:`./what-is-rpp` +AMD ROCm Performance Primitives (RPP) is a high-performance computer vision +library for AMD processors that have HIP, OpenCL, or CPU backends. RPP provides a way to utilize all the hardware available for training and augmentation. -Our code is open and hosted at `https://github.com/ROCm/rpp `_. - -The RPP documentation is structured as follows: +The RPP public repository is located at `https://github.com/ROCm/rpp `_. .. grid:: 2 :gutter: 3 .. grid-item-card:: Install - * :doc:`Install RPP <./install/install>` + * :doc:`RPP prerequisites <./install/rpp-prerequisites>` + * :doc:`Installing RPP <./install/rpp-install>` + * :doc:`Installing RPP with the package installer <./install/rpp-install-with-installer>` + * :doc:`Building and installing RPP from source <./install/rpp-build-and-install>` + * :doc:`Verifying the RPP installation <./install/rpp-verify-install>` .. grid-item-card:: Reference + * :doc:`Supported RPP functionalities and variants <./reference/rpp-supported-functionalities>` * :doc:`API library <./doxygen/html/globals>` * :doc:`Modules <./doxygen/html/files>` * :doc:`Data structures <./doxygen/html/annotated>` * :doc:`Deprecated functions <./doxygen/html/deprecated>` -To contribute to the documentation refer to -:doc:`Contributing to ROCm `. +To contribute to the documentation refer to :doc:`Contributing to ROCm `. You can find licensing information on the :doc:`Licensing ` page. diff --git a/docs/install/install.rst b/docs/install/install.rst deleted file mode 100644 index 3300d947e..000000000 --- a/docs/install/install.rst +++ /dev/null @@ -1,192 +0,0 @@ -.. meta:: - :description: rocAL documentation and API reference library - :keywords: rocAL, ROCm, API, documentation - -.. _install: - -******************************************************************** -Installation -******************************************************************** - -This chapter provides information about the installation of RPP and related packages. - -Prerequisites -============================= - -* Linux distribution - - Ubuntu 22.04 or 24.04 - - RedHat 8 or 9 - - SLES 15-SP5 - -* `ROCm supported hardware `_ - -* Install ROCm with `amdgpu-install `_ with ``--usecase=rocm`` - -* AMD Clang++ Version 18.0.0 or later - installed with ROCm - - * NOTE: For CPU only backend use Clang Version `5.0.1` and above - - .. code-block:: shell - - sudo apt-get install clang - - * Required compiler support - - C++ Version `17` and above - - OpenMP - - Threads - -* CMake Version `3.10` and above - - .. code-block:: shell - - sudo apt-get install cmake - -* IEEE 754-based half-precision floating-point library (half.hpp) - - .. code-block:: shell - - sudo apt-get install half - - .. note:: - Use appropriate package manager depending on the OS - - -Build and install instructions -================================ - -The installation process uses the following steps: - -.. _package-install: - -Package install -------------------------------- - -Install RPP runtime, development, and test packages. - -* Runtime package - `rpp` only provides the rpp library `librpp.so` -* Development package - `rpp-dev`/`rpp-devel` provides the library, header files, and samples -* Test package - `rpp-test` provides ctest to verify installation - -.. note:: - Package installation will auto install all dependencies. - -On Ubuntu -^^^^^^^^^^^^^^^ - -.. code-block:: shell - - sudo apt install rpp rpp-dev rpp-test - -On RHEL -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: shell - - sudo yum install rpp rpp-devel rpp-test - - -On SLES -^^^^^^^^^^^^^^ - -.. code-block:: shell - - sudo zypper install rpp rpp-devel rpp-test - - -.. _source-install: - -Source build and install ---------------------------- - -The process for installing is as follows: - -* Clone RPP git repository - - .. code-block:: shell - - git clone https://github.com/ROCm/rpp.git - - .. note:: - RPP has support for two GPU backends: **OPENCL** and **HIP** - -* Instructions for building RPP with the **HIP** GPU backend (default GPU backend): - - .. code-block:: shell - - mkdir build-hip - cd build-hip - cmake ../rpp - make -j8 - sudo make install - - - + Run tests - `test option instructions `_ - - .. code-block:: shell - - make test - - .. note:: - `make test` requires installation of `test suite prerequisites `_ - -* Instructions for building RPP with **OPENCL** GPU backend - - .. code-block:: shell - - mkdir build-ocl - cd build-ocl - cmake -DBACKEND=OCL ../rpp - make -j8 - sudo make install - -Verify installation -========================= - -The installer will copy - -* Libraries into `/opt/rocm/lib` -* Header files into `/opt/rocm/include/rpp` -* Samples folder into `/opt/rocm/share/rpp` -* Documents folder into `/opt/rocm/share/doc/rpp` - -Verify with `rpp-test` package --------------------------------------------- - -Test package will install `ctest` module to test `rpp`. Use the following steps to test the installation: - -.. code-block:: shell - - mkdir rpp-test && cd rpp-test - cmake /opt/rocm/share/rpp/test/ - ctest -VV - -.. note:: - Installation of `test suite prerequisites `_ are required to run tests - -Test RPP functionalities --------------------------------------------- - -To test the functionalities of `rpp`, run the code shown for your backend: - -* HIP - - .. code-block:: shell - - cd rpp/utilities/rpp-unittests/HIP_NEW - ./testAllScript.sh - - -* OpenCL - - .. code-block:: shell - - cd rpp/utilities/rpp-unittests/OCL_NEW - ./testAllScript.sh - - -* CPU - - .. code-block:: shell - - cd rpp/utilities/rpp-unittests/HOST_NEW - ./testAllScript.sh diff --git a/docs/install/rpp-build-and-install.rst b/docs/install/rpp-build-and-install.rst new file mode 100644 index 000000000..5bebff64a --- /dev/null +++ b/docs/install/rpp-build-and-install.rst @@ -0,0 +1,52 @@ +.. meta:: + :description: Building and installing ROCm Performance Primitives + :keywords: rpp, ROCm Performance Primitives, ROCm, documentation, installing, building, source code + +************************************************************************** +Building and installing ROCm Performance Primitives +************************************************************************** + +ROCm Performance Primitives (RPP) supports HIP and OpenCL backends running on `accelerators based on the CDNA architecture `_, and supports CPU-only backends on CPUs that support PCIe™ atomics. + +On OpenCL and HIP backends, RPP requires ROCm installed with the `AMDGPU installer `_ and the ``rocm`` usecase: + +.. code:: shell + + sudo amdgpu-install --usecase=rocm + +Clone the source code from the `RPP GitHub repository `_, then use the following commands to build and install RPP: + +.. tab-set:: + + .. tab-item:: HIP + + .. code:: shell + + mkdir build-hip + cd build-hip + cmake ../ + make -j8 + sudo make install + + .. tab-item:: OpenCL + + .. code:: shell + + mkdir build-ocl + cd build-ocl + cmake -DBACKEND=OPENCL ../ + make -j8 + sudo make install + + .. tab-item:: CPU-only + + .. code:: shell + + mkdir build-cpu + cd build-cpu + cmake -DBACKEND=CPU ../ + make -j8 + sudo make install + + + diff --git a/docs/install/rpp-install-with-installer.rst b/docs/install/rpp-install-with-installer.rst new file mode 100644 index 000000000..b97c2b38c --- /dev/null +++ b/docs/install/rpp-install-with-installer.rst @@ -0,0 +1,67 @@ +.. meta:: + :description: Installing ROCm Performance Primitives with the package installer + :keywords: rpp, ROCm Performance Primitives, ROCm, documentation, installing, package installer + +******************************************************************** +Installing ROCm Performance Primitives with the package installer +******************************************************************** + +There are three ROCm Performance Primitives (RPP) packages available: + +``rpp``: The RPP runtime package. This is the basic package that only installs the ``librpp.so`` library. + +``rpp-dev``: The RPP development package. This package installs the ``librpp.so`` library, the RPP header files, and the RPP samples. + +``rpp-test``: A test package that provides CTest to verify the installation. + +All the required dependencies are installed when the package installation method is used. + +Use the following commands to install only the RPP runtime package: + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rpp + + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rpp + + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rpp + + +Use the following commands to install all three RPP packages: + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rpp rpp-dev rpp-test + + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rpp rpp-devel rpp-test + + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rpp rpp-devel rpp-test + diff --git a/docs/install/rpp-install.rst b/docs/install/rpp-install.rst new file mode 100644 index 000000000..118af1ecd --- /dev/null +++ b/docs/install/rpp-install.rst @@ -0,0 +1,15 @@ +.. meta:: + :description: Installing ROCm Performance Primitives + :keywords: rpp, ROCm Performance Primitives, ROCm, documentation, installing + +******************************************************************** +Installing ROCm Performance Primitives +******************************************************************** + +ROCm Performance Primitives (RPP) supports HIP, OpenCL, and CPU-only backends. + +A :doc:`package installer <./rpp-install-with-installer>` is available for installing either only the RPP runtime, or the RPP runtime and development packages. + +RPP can also be :doc:`built from source <./rpp-build-and-install>`. + +After installing RPP, :doc:`verify the installation using the test suite <./rpp-verify-install>`. diff --git a/docs/install/rpp-prerequisites.rst b/docs/install/rpp-prerequisites.rst new file mode 100644 index 000000000..5cb027678 --- /dev/null +++ b/docs/install/rpp-prerequisites.rst @@ -0,0 +1,32 @@ +.. meta:: + :description: ROCm Performance Primitives (RPP) prerequisites + :keywords: RPP, ROCm, Performance Primitives, prerequisites + +******************************************************************** +ROCm Performance Primitives prerequisites +******************************************************************** + +ROCm Performance Primitives (RPP) is supported on the following operating systems: + +* Ubuntu version 22.04 or 24.04 +* RedHat version 8 or 9 +* SLES 15-SP5 + +The following compilers and libraries are required to build and install RPP: + +* half, the half-precision floating-point library, version 1.12.0 or later +* libstdc++-12-dev for Ubuntu 22.04 only +* Clang version 5.0.1 or later for CPU-only backends +* AMD Clang++ Version 18.0.0 or later for HIP and OpenCL backends + +With the following compiler support: + +* C++17 or later +* OpenMP +* Threads + +On OpenCL and HIP backends, RPP requires ROCm installed with the `AMDGPU installer `_ and the ``rocm`` usecase running on `accelerators based on the CDNA architecture `_. + +On CPU-only backends, RPP requires CPUs that support PCIe™ atomics. + +The `test suite prerequisites `_ are required to build the RPP test suite. diff --git a/docs/install/rpp-verify-install.rst b/docs/install/rpp-verify-install.rst new file mode 100644 index 000000000..7aac9cf37 --- /dev/null +++ b/docs/install/rpp-verify-install.rst @@ -0,0 +1,50 @@ +.. meta:: + :description: Installing ROCm Performance Primitives + :keywords: rpp, ROCm Performance Primitives, ROCm, documentation, installing, package installer + +******************************************************************** +Verifying the ROCm Performance Primitives installation +******************************************************************** + +After installation, verify that all the ROCm Performance Primitives (RPP) files have been copied to the right locations: + +* Libraries: ``/opt/rocm/lib`` +* Header files: ``/opt/rocm/include/rpp`` +* Samples: ``/opt/rocm/share/rpp`` +* Documentation: ``/opt/rocm/share/doc/rpp`` + +You can verify your installation using the CTest module. You will need to install the `test suite prerequisites `_ before building and running the tests. + +.. code-block:: shell + + mkdir rpp-test + cd rpp-test + cmake /opt/rocm/share/rpp/test/ + ctest -VV + +To test RPP's functionality, run ``testALLScript.sh``: + +.. tab-set:: + + .. tab-item:: HIP + + .. code:: shell + + cd rpp/utilities/rpp-unittests/HIP_NEW + ./testAllScript.sh + + .. tab-item:: OpenCL + + .. code:: shell + + cd rpp/utilities/rpp-unittests/OCL_NEW + ./testAllScript.sh + + + .. tab-item:: CPU-only + + .. code:: shell + + cd rpp/utilities/rpp-unittests/HOST_NEW + ./testAllScript.sh + \ No newline at end of file diff --git a/docs/what-is-rpp.rst b/docs/reference/rpp-supported-functionalities.rst similarity index 78% rename from docs/what-is-rpp.rst rename to docs/reference/rpp-supported-functionalities.rst index d68d75d5d..e1e111bce 100644 --- a/docs/what-is-rpp.rst +++ b/docs/reference/rpp-supported-functionalities.rst @@ -1,24 +1,7 @@ -.. meta:: - :description: What is RPP - :keywords: RPP, ROCm, Performance Primitives, documentation - -.. _what-is: - -******************************************************************** -What is RPP? -******************************************************************** - -AMD ROCm Performance Primitives (RPP) library is a comprehensive, high-performance computer -vision library for AMD processors that have HIP, OpenCL, or CPU backends. - -.. image:: ./data/rpp_structure_4.png - :alt: RPP Functions - Supported functionalities and variants ========================================== -The following tables show the CPU and GPU support for various RPP functionalities and variants. You -can view image samples following the tables. +The following tables show the CPU and GPU support for ROCm Performance Primitives (RPP) functionalities and variants. Image augmentations ----------------------------------------------------------------------------------------------- @@ -197,22 +180,4 @@ Computer vision "hog", "✅", "❌" "remap", "✅", "❌" "tensor matrix multiply", "✅", "✅" - "tensor transpose", "✅", "✅" - -Image examples ---------------------------------------------------------------- - -.. image:: ./data/supported_functionalities_samples.jpg - :alt: Supported function samples - -3D images -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following is an example of a 3D medical image before and after ``fused_multiply_add_scalar``. - -.. list-table:: - - * - Original image - - Modified image - * - .. image:: ./data/niftiInput.gif - - .. image:: ./data/niftiOutputBrightened.gif + "tensor transpose", "✅", "✅" \ No newline at end of file diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 182f7e7cf..5d0f60d54 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -5,17 +5,22 @@ defaults: maxdepth: 6 root: index subtrees: -- entries: - - file: what-is-rpp.rst - - caption: Install entries: - - file: install/install.rst - title: Install RPP + - file: install/rpp-prerequisites.rst + title: RPP prerequisites + - file: install/rpp-install-with-installer.rst + title: Install RPP with package installer + - file: install/rpp-build-and-install.rst + title: Build and install RPP + - file: install/rpp-verify-install.rst + title: Verify the RPP installation - caption: Reference entries: + - file: reference/rpp-supported-functionalities.rst + title: Supported functionalities and variants - file: doxygen/html/globals title: API library subtrees: