From 8167cfe7a6205d5172f2ff8a8693980d76167522 Mon Sep 17 00:00:00 2001 From: Jeffrey Novotny Date: Thu, 28 Nov 2024 10:43:29 -0500 Subject: [PATCH] Refactor and reformat MIOpen index and install docs --- docs/index.rst | 37 ++-- docs/install/build-source.rst | 289 +++++++++++++++++++++++++++ docs/install/docker-build.rst | 84 ++------ docs/install/embed.rst | 126 ++++++------ docs/install/install.rst | 350 +++++---------------------------- docs/install/prerequisites.rst | 40 ++++ docs/sphinx/_toc.yml.in | 30 +-- docs/what-is-miopen.rst | 16 -- 8 files changed, 494 insertions(+), 478 deletions(-) create mode 100644 docs/install/build-source.rst create mode 100644 docs/install/prerequisites.rst delete mode 100644 docs/what-is-miopen.rst diff --git a/docs/index.rst b/docs/index.rst index d079248229..e8a5fd42f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,32 +1,32 @@ .. meta:: - :description: MIOpen documentation + :description: Documentation for MIOpen, :keywords: MIOpen, ROCm, API, documentation ******************************************************************** MIOpen documentation ******************************************************************** -Welcome to our documentation home page. To learn more about MIOpen, refer to -:doc:`What is MIOpen? <./what-is-miopen>` +MIOpen is AMD's open-source, deep-learning primitives library for GPUs. It implements fusion to +optimize for memory bandwidth and GPU launch overheads, providing an auto-tuning infrastructure +to overcome the large design space of problem configurations. It also implements different algorithms +to optimize convolutions for different filter and input sizes. -Our documentation is structured as follows: +MIOpen is one of the first libraries to publicly support the ``bfloat16`` data type for convolutions, which +allows for efficient training at lower precision without loss of accuracy. + +The MIOpen public repository is located at ``_. .. grid:: 2 :gutter: 3 .. grid-item-card:: Install + * :doc:`MIOpen prerequisites <./install/prerequisites>` * :doc:`Install MIOpen <./install/install>` + * :doc:`Build MIOpen from source <./install/build-source>` * :doc:`Build MIOpen for embedded systems <./install/embed>` * :doc:`Build MIOpen using Docker <./install/docker-build>` - - .. grid-item-card:: Reference - - * :doc:`API library ` - - * :doc:`Modules <./doxygen/html/modules>` - * :doc:`Datatypes ` - + .. grid-item-card:: Conceptual * :doc:`MI200 alternate implementation <./conceptual/MI200-alt-implementation>` @@ -41,8 +41,15 @@ Our documentation is structured as follows: * :doc:`Log & debug <./how-to/debug-log>` * :doc:`Use the find APIs & immediate mode <./how-to/find-and-immediate>` -To contribute to the documentation refer to + .. grid-item-card:: Reference + + * :doc:`API library ` + + * :doc:`Modules <./doxygen/html/modules>` + * :doc:`Datatypes ` + +For information on contributing to the MIOpen code base, see `Contributing to ROCm `_. -You can find licensing information for all ROCm components on the -`ROCm licensing `_ page. +For licensing information for all ROCm components, see +`ROCm licensing `_. diff --git a/docs/install/build-source.rst b/docs/install/build-source.rst new file mode 100644 index 0000000000..a657deae2f --- /dev/null +++ b/docs/install/build-source.rst @@ -0,0 +1,289 @@ +.. meta:: + :description: Building MIOpen from source + :keywords: MIOpen, ROCm, API, documentation, build, installation, testing + +******************************************************************** +Build MIOpen from source +******************************************************************** + +This topic discusses how to build MIOpen from source and configure the resulting application. +It also explains how to build the library and driver and run the tests. For a list of MIOpen +prerequisites, see :doc:`MIOpen prerequisites <./prerequisites>`. To install MIOpen from a +package, see :doc:`install MIOpen <./install>`. + +Building MIOpen +================================================ + +You can build MIOpen form source using either a HIP backend or an OpenCL backend. + +HIP backend +-------------------------------------------------------------------------------------------------------- + +To build MIOpen using the HIP backend (in ROCm 3.5 and later), follow these steps: + +#. Create the build directory: + + .. code:: shell + + mkdir build; cd build; + +#. Configure CMake. Set the backend using the ``-DMIOPEN_BACKEND`` CMake variable and + set the C++ compiler to ``clang++``. The command to build MIOpen with a HIP backend follows this format: + + .. code:: shell + + export CXX= + cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH=";;" .. + + An example of a CMake build is: + + .. code:: shell + + export CXX=/opt/rocm/llvm/bin/clang++ && \ + cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" .. + + .. note:: + + When specifying the path for the ``CMAKE_PREFIX_PATH`` variable, **do not** use the tilde (``~``) + symbol to represent the home directory. + +OpenCL backend +-------------------------------------------------------------------------------------------------------- + +To build MIOpen using an OpenCL backend, run the following command: + +.. code:: shell + + cmake -DMIOPEN_BACKEND=OpenCL .. + +.. note:: + + OpenCL is deprecated and the HIP backend is recommended instead. To install MIOpen using HIP, follow the instructions in + the preceding section. + +The preceding code assumes OpenCL is installed in one of the standard locations. If not, then manually +set these CMake variables: + +.. code:: shell + + cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER= -DOPENCL_LIBRARIES= -DOPENCL_INCLUDE_DIRS= .. + +Here's an example showing how to configure the dependency path for an environment (applies to ROCm version 3.5 and later): + +.. code:: shell + + cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER=/opt/rocm/llvm/bin/clang++ -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" .. + +.. _setting-up-locations: + +Setting the install location +-------------------------------------------------------------------------------------------------------- + +By default, the install location is set to ``/opt/rocm``. To change this, use ``CMAKE_INSTALL_PREFIX``: + +.. code:: shell + + cmake -DMIOPEN_BACKEND=HIP -DCMAKE_INSTALL_PREFIX= .. + +System performance database and user database +-------------------------------------------------------------------------------------------------------- + +The default path to the system performance database (System PerfDb) is ``miopen/share/miopen/db/`` +within the install location. The default path to the user performance database (User PerfDb) is +``~/.config/miopen/``. Setting ``BUILD_DEV`` for development purposes changes the default path for +both database files to the source directory: + +.. code:: shell + + cmake -DMIOPEN_BACKEND=HIP -DBUILD_DEV=On .. + +To customize the database paths, use the ``MIOPEN_SYSTEM_DB_PATH`` (for the System PerfDb) +and ``MIOPEN_USER_DB_PATH`` (for the User PerfDb) CMake variables. + +To learn more, see :doc:`using the performance database <../conceptual/perfdb>`. + +Persistent program cache +-------------------------------------------------------------------------------------------------------- + +By default, MIOpen caches device programs in the ``~/.cache/miopen/`` directory. Within the cache +directory, there is a directory for each version of MIOpen. To change the location of the cache +directory during configuration, use the ``-DMIOPEN_CACHE_DIR=`` flag. + +To disable the cache during runtime, set the ``MIOPEN_DISABLE_CACHE=1`` environmental +variable. + +For MIOpen version 2.3 and earlier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the compiler changes or you modify the kernels, then you must delete the cache for the MIOpen +version in use, for example, ``rm -rf ~/.cache/miopen/``. For more +information, see :doc:`kernel cache <../conceptual/cache>`. + +For MIOpen version 2.4 and later +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MIOpen's kernel cache directory is versioned, so cached kernels don't collide when upgrading +from an earlier version. + +Changing the CMake configuration +-------------------------------------------------------------------------------------------------------- + +The configuration can be changed after running CMake by using ``ccmake``: + +.. code:: shell + + ccmake .. + +or + +.. code:: shell + + cmake-gui: cmake-gui .. + +The ``ccmake`` program can be downloaded using the Linux package ``cmake-curses-gui``, but is not +available on Windows. + +Building the library +========================================================= + +You can build the library from the ``build`` directory using the ``Release`` configuration: + +.. code:: shell + + cmake --build . --config Release + +or + +.. code:: shell + + make + +You can install it using the ``install`` target: + +.. code:: shell + + cmake --build . --config Release --target install + +or + +.. code:: shell + + make install + +This command installs the library to the ``CMAKE_INSTALL_PREFIX`` directory path. + +Building the driver +========================================================= + +MIOpen provides an application driver that can run any layer in isolation and measure +library performance and verification. + +To build the driver, use the ``MIOpenDriver`` target: + +.. code:: shell + + cmake --build . --config Release --target MIOpenDriver + +or + +.. code:: shell + + make MIOpenDriver + +Running the tests +========================================================= + +To run tests, use the ``check`` target: + +.. code:: shell + + cmake --build . --config Release --target check + +or + +.. code:: shell + + make check + +To build and run a single test, use the following commands: + +.. code:: shell + + cmake --build . --config Release --target test_tensor + ./bin/test_tensor + +Formatting the code +========================================================= + +To format the code using ``clang-format``, use this command: + +.. code:: shell + + clang-format-10 -style=file -i + +To format the code per commit, install githooks: + +.. code:: shell + + ./.githooks/install + +Storing large file using Git Large File Storage +========================================================= + +Git Large File Storage (LFS) replaces large files, such as audio samples, videos, datasets, and graphics +with text pointers inside Git, while storing the file contents on a remote server. MIOpen uses Git +LFS to store large files, such as kernel database files (``*.kdb``), which are normally > 0.5 GB. + +To install Git LFS, use these commands: + +.. code:: shell + + sudo apt install git-lfs + git lfs install + +In the Git repository where you want to use Git LFS, track the file type using the following code. If the +file type is already being tracked, you can skip this step: + +.. code:: shell + + git lfs track "*.file_type" + git add .gitattributes + +To pull all files or a single large file, use: + +.. code:: shell + + git lfs pull --exclude= + +or + +.. code:: shell + + git lfs pull --exclude= --include "filename" + +Update the large files and push to GitHub using the following sequence of commands: + +.. code:: shell + + git add my_large_files + git commit -m "the message" + git push + +Installing the dependencies manually +=============================================================== + +If you're using Ubuntu v16, you can install the ``Boost`` packages using: + +.. code:: shell + + sudo apt-get install libboost-dev + sudo apt-get install libboost-system-dev + sudo apt-get install libboost-filesystem-dev + +.. note:: + + By default, MIOpen attempts to build with Boost statically linked libraries. To build + with dynamically linked Boost libraries, use the ``-DBoost_USE_STATIC_LIBS=Off`` flag during the + configuration stage. However, this is not recommended. + +You must install the ``half`` header from the `half website `_. diff --git a/docs/install/docker-build.rst b/docs/install/docker-build.rst index 620bdbb797..876f679caa 100644 --- a/docs/install/docker-build.rst +++ b/docs/install/docker-build.rst @@ -1,6 +1,6 @@ .. meta:: :description: Build MIOpen using Docker - :keywords: MIOpen, ROCm, API, documentation + :keywords: MIOpen, ROCm, API, documentation, Docker ******************************************************************** Build MIOpen using Docker @@ -10,80 +10,28 @@ You can build MIOpen using Docker by either downloading a prebuilt image or crea .. note:: - For ease of use, we recommended using the prebuilt Docker image. + For ease of use, the prebuilt Docker image is recommended. -* Downloading a prebuilt image +* Downloading a prebuilt image - You can find prebuilt Docker images at - `ROCm Docker Hub `_. + You can find prebuilt Docker images at `ROCm Docker Hub `_. -* Building your own image +* Building your own image + + #. To build the Docker image, use ``docker build``: - .. code-block:: bash + .. code-block:: bash - docker build -t miopen-image . + docker build -t miopen-image . - To enter the development environment, use ``docker run``. For example: + #. To enter the development environment, use ``docker run``, for example: - .. code-block:: bash + .. code-block:: bash - docker run -it -v $HOME:/data --privileged --rm --device=/dev/kfd --device /dev/dri:/dev/dri:rw - --volume /dev/dri:/dev/dri:rw -v /var/lib/docker/:/var/lib/docker --group-add video - --cap-add=SYS_PTRACE --security-opt seccomp=unconfined miopen-image + docker run -it -v $HOME:/data --privileged --rm --device=/dev/kfd --device /dev/dri:/dev/dri:rw + --volume /dev/dri:/dev/dri:rw -v /var/lib/docker/:/var/lib/docker --group-add video + --cap-add=SYS_PTRACE --security-opt seccomp=unconfined miopen-image - Once in the Docker environment, use ``git clone MIOpen``. You can now start building MIOpen using - CMake. + #. Enter the Docker environment and run ``git clone MIOpen``. You can now build MIOpen using + CMake. For instructions on how to build MIOpen from source, see :doc:`building MIOpen <./build-source>`. -Building MIOpen from source -========================================================== - -Use the following instructions to build MIOpen from source. - -1. Create a build directory: - - .. code-block:: bash - - mkdir build; cd build; - -2. Configure CMake using either an MIOpen or a HIP backend. - - **MIOpen backend**: - - Set your preferred backend using the ``-DMIOPEN_BACKEND`` CMake variable. - - **HIP backend (ROCm 3.5 and later)**: - - First, set the C++ compiler to ``clang++``: - - .. code-block:: bash - - export CXX= - - Then, run the following command to configure CMake: - - .. code-block:: bash - - cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH=";;" .. - - For example, you can set CMake to: - - .. code-block:: bash - - export CXX=/opt/rocm/llvm/bin/clang++ && \ - cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" .. - - .. note:: - - When specifying the path for ``CMAKE_PREFIX_PATH``, **do not** use the tilde (~) shorthand - for the home directory. - - -Choosing an install location -------------------------------------------------------------------------------------- - -By default, the install location is set to ``/opt/rocm``. If you used a different install location, set your -install path using ``CMAKE_INSTALL_PREFIX``: - -.. code-block:: bash - - cmake -DMIOPEN_BACKEND=OpenCL -DCMAKE_INSTALL_PREFIX= .. diff --git a/docs/install/embed.rst b/docs/install/embed.rst index 1567027887..6ccdaad4c7 100644 --- a/docs/install/embed.rst +++ b/docs/install/embed.rst @@ -1,121 +1,123 @@ .. meta:: :description: Build MIOpen for embedded systems - :keywords: MIOpen, ROCm, API, documentation + :keywords: MIOpen, ROCm, API, documentation, embedded, build ******************************************************************** Build MIOpen for embedded systems ******************************************************************** -1. Install dependencies. The default location is ``/usr/local``: +Follow these steps to build and configure MIOpen for an embedded system. - .. code:: cpp +1. Install the dependencies. The default install location is ``/usr/local``: - cmake -P install_deps.cmake --minimum --prefix /some/local/dir + .. code:: cpp -2. Create the build directory. - - .. code:: cpp + cmake -P install_deps.cmake --minimum --prefix /some/local/dir - mkdir build; cd build; +2. Create the build directory. -3. Configure for an embedded build. + .. code:: cpp - The minimum static build configuration line, without an embedded precompiled kernels package or - FindDb is: + mkdir build; cd build; - .. code:: cpp +3. Add the embedded build configuration. + + The minimum static build configuration, without an + embedded precompiled kernels package or + FindDb, is the following: - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BACKEND=HIP -DMIOPEN_EMBED_BUILD=On -DCMAKE_PREFIX_PATH="/some/local/dir" .. + .. code:: cpp + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BACKEND=HIP -DMIOPEN_EMBED_BUILD=On -DCMAKE_PREFIX_PATH="/some/local/dir" .. - To enable HIP kernels in MIOpen while using embedded builds, add - ``-DMIOPEN_USE_HIP_KERNELS=On`` to configure line. For example: + To enable HIP kernels in MIOpen for embedded builds, add + ``-DMIOPEN_USE_HIP_KERNELS=On`` to the command line. For example: - .. code:: cpp + .. code:: cpp - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BACKEND=HIP -DMIOPEN_USE_HIP_KERNELS=On -DMIOPEN_EMBED_BUILD=On -DCMAKE_PREFIX_PATH="/some/local/dir" .. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BACKEND=HIP -DMIOPEN_USE_HIP_KERNELS=On -DMIOPEN_EMBED_BUILD=On -DCMAKE_PREFIX_PATH="/some/local/dir" .. 4. Embed FindDb and PerfDb. - FindDb provides a database of known convolution inputs. This allows you to use the best tuned - kernels for your network. Embedding FindDb requires a semicolon-separated list of architecture CU - pairs to embed on-disk databases in the binary (e.g., ``gfx906_60;gfx900_56``). + FindDb provides a database of known convolution inputs. It allows you to use the best tuned + kernels for your network. To embed on-disk databases in the binary with FindDb, use ``DMIOPEN_EMBED_DB`` with + a semicolon-separated list of architecture-CU pairs (for example, ``gfx906_60;gfx900_56``). - .. code:: cpp + .. code:: cpp - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_EMBED_BUILD=On -DMIOPEN_EMBED_DB=gfx900_56 .. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_EMBED_BUILD=On -DMIOPEN_EMBED_DB=gfx900_56 .. - This configures the build directory for embedding (FindDb and PerfDb). + This configures embedding for the build directory for both FindDb and PerfDb. 5. Embed the precompiled kernels package. - To prevent the loss of performance due to compile-time overhead, an MIOpen build can embed the - precompiled kernels package. This package contains convolution kernels of known inputs, and allows - you to avoid compiling kernels during runtime. + An MIOpen build can embed the precompiled kernels package, + preventing reduced performance due to compile-time overhead. This package contains the convolution kernels of known inputs + to avoid the runtime compilation of kernels. - * Embed the precompiled package using a package install. + There are two options for embedding the precompiled kernels package. - .. code:: bash + * Embed the precompiled package using a package install. - apt-get install miopenkernels-- + .. code:: bash - Where ```` is the GPU architecture (e.g., gfx900, gfx906) and ```` is the number of - compute units (CUs) available in the GPU (e.g., 56, 64). + apt-get install miopenkernels-- - If you choose not to install the precompiled kernel package, there is no impact to the functioning of - MIOpen because MIOpen compiles these kernels on the target machine once the kernel is run. - However, the compilation step may significantly increase the startup time for different operations. + Where ```` is the GPU architecture (for example, ``gfx900`` or ``gfx906``) and ```` is the number of + compute units (CUs) available in the GPU (for example, 56 or 64). - The ``utils/install_precompiled_kernels.sh`` script automates the above process. It queries your - machine for the GPU architecture and then installs the appropriate package. You can invoke it using: + There is no functional impact to MIOpen if you choose not to install the + precompiled kernel package. This is because MIOpen compiles these kernels on the target machine after the kernel is run. + However, the compilation step might significantly increase the startup time for some operations. - .. code:: cpp + The ``utils/install_precompiled_kernels.sh`` script automates this process. It queries your + system for the GPU architecture and then installs the appropriate package. To invoke it, use: - ./utils/install_precompiled_kernels.sh + .. code:: cpp - To embed the precompiled kernels package, configure CMake using the - ``MIOPEN_BINCACHE_PATH``. + ./utils/install_precompiled_kernels.sh - .. code:: cpp + To embed the precompiled kernels package, configure CMake using ``MIOPEN_BINCACHE_PATH``. - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/path/to/package/install -DMIOPEN_EMBED_BUILD=On .. + .. code:: cpp - * Using the URL to a kernels binary. You can use the ``MIOPEN_BINCACHE_PATH`` flag with a URL that - contains the binary. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/path/to/package/install -DMIOPEN_EMBED_BUILD=On .. - .. code:: cpp + Here's an example that uses the gfx900 architecture and 56 CUs: - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/URL/to/binary -DMIOPEN_EMBED_BUILD=On .. + .. code:: cpp - Precompiled kernels packages are installed in ``/opt/rocm/miopen/share/miopen/db``. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/opt/rocm/miopen/share/miopen/db/gfx900_56.kdb -DMIOPEN_EMBED_BUILD=On .. - Here's an example with gfx900 architecture and 56 CUs: + * Embed the precompiled package using the URL of a kernels binary. Use the ``MIOPEN_BINCACHE_PATH`` flag with the URL + of the binary. - .. code:: cpp + .. code:: cpp - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/opt/rocm/miopen/share/miopen/db/gfx900_56.kdb -DMIOPEN_EMBED_BUILD=On .. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/URL/to/binary -DMIOPEN_EMBED_BUILD=On .. - As of ROCm 3.8 and MIOpen 2.7, precompiled kernels binaries are located at - `repo.radeon.com `_. + The precompiled kernels packages are installed in ``/opt/rocm/miopen/share/miopen/db``. - Here's an example with gfx906 architecture and 64 CUs: + As of ROCm version 3.8 and MIOpen version 2.7, precompiled kernels binaries are located at + `repo.radeon.com `_. - .. code:: cpp + Here's an example that uses the gfx906 architecture and 64 CUs: - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=http://repo.radeon.com/rocm/miopen-kernel/rel-3.8/gfx906_60.kdb -DMIOPEN_EMBED_BUILD=On .. + .. code:: cpp + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=http://repo.radeon.com/rocm/miopen-kernel/rel-3.8/gfx906_60.kdb -DMIOPEN_EMBED_BUILD=On .. 6. Full configuration line. - To build MIOpen statically and embed the performance database, FindDb, and the precompiled - kernels binary: + To build MIOpen statically and embed the performance database, FindDb, and the precompiled + kernels binary, follow this example: - .. code:: cpp + .. code:: cpp - CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/path/to/package/install -DMIOPEN_EMBED_BUILD=On -DMIOPEN_EMBED_DB=gfx900_56 .. + CXX=/opt/rocm/llvm/bin/clang++ cmake -DMIOPEN_BINCACHE_PATH=/path/to/package/install -DMIOPEN_EMBED_BUILD=On -DMIOPEN_EMBED_DB=gfx900_56 .. - After configuration is complete, run: + After configuration is complete, run the following command: - .. code:: cpp + .. code:: cpp - make -j + make -j diff --git a/docs/install/install.rst b/docs/install/install.rst index 077701ffd2..56cf947408 100644 --- a/docs/install/install.rst +++ b/docs/install/install.rst @@ -1,353 +1,97 @@ .. meta:: - :description: Installing MIOpen - :keywords: MIOpen, ROCm, API, documentation + :description: Installing MIOpen from a package + :keywords: MIOpen, ROCm, API, documentation, install, package ******************************************************************** -Installing MIOpen +Install MIOpen ******************************************************************** -To install MIOpen, you must first install these prerequisites: +To install MIOpen from a package, choose either a pre-built package for your Linux +distribution or choose a pre-compiled kernels package. For a list of MIOpen +prerequisites, see :doc:`MIOpen prerequisites <./prerequisites>`. To build MIOpen from +source, see :doc:`build MIOpen from source <./build-source>`. -* A :doc:`ROCm `-enabled platform -* A base software stack that includes either: - - * HIP (HIP and HCC libraries and header files) - * OpenCL (OpenCL libraries and header files)--this is now deprecated - -* `ROCm CMake `_: provides CMake modules for common - build tasks needed for the ROCm software stack -* `Half `_: IEEE 754-based, half-precision floating-point library -* `Boost `_: Version 1.79 is recommended, as older versions may need patches - to work on newer systems +Installing using a pre-built package +============================================================== - * MIOpen uses ``boost-system`` and ``boost-filesystem`` packages to enable persistent - :doc:`kernel cache <../conceptual/cache>` +To install MIOpen on Ubuntu, use ``apt-get install miopen-hip``. -* `SQLite3 `_: A reading and writing performance database -* lbzip2: A multi-threaded compress or decompress utility -* :doc:`rocBLAS `: AMD's library for Basic Linear Algebra Subprograms (BLAS) on the - ROCm platform. +If you are using OpenCL, use ``apt-get install miopen-opencl``. (This is not recommended because +OpenCL is deprecated.) - * Minimum version branch for pre-ROCm 3.5 - `master-rocm-2.10 `_ - * Minimum version branch for post-ROCm 3.5 - `master-rocm-3.5 `_ +.. note:: -* `Multi-Level Intermediate Representation (MLIR) `_ with its - MIOpen dialect to support and complement kernel development -* :doc:`Composable Kernel `: A C++ templated device library for - GEMM-like and reduction-like operators. + You can't install both backends on the same system simultaneously. To switch to a different + backend, completely uninstall the existing backend prior to installing + the new backend. -Installing with pre-built packages +Installing using a kernels package ============================================================== -You can install MIOpen on Ubuntu using ``apt-get install miopen-hip``. - -If using OpenCL, you can use ``apt-get install miopen-opencl`` (but this is not recommended, as -OpenCL is deprecated). - -Note that you can't install both backends on the same system simultaneously. If you want a different -backend other than what currently exists, completely uninstall the existing backend prior to installing -the new backend. - -Installing with a kernels package --------------------------------------------------------------------------------------------------------- - MIOpen provides an optional pre-compiled kernels package to reduce startup latency. These -precompiled kernels comprise a select set of popular input configurations. We'll expand these kernels -in future releases to include additional coverage. +precompiled kernels consist of a select set of popular input configurations. This collection of kernels +will continue to expand to include additional coverage. -Note that all compiled kernels are locally cached in the ``$HOME/.cache/miopen/`` folder, so -precompiled kernels reduce the startup latency only for the first run of a neural network. Precompiled -kernels don't reduce startup time on subsequent runs. +.. note:: + + All compiled kernels are locally cached in the ``$HOME/.cache/miopen/`` folder, so these + pre-compiled kernels only reduce the startup latency for the first run of a neural network. Pre-compiled + kernels don't reduce the startup time on subsequent runs. To install the kernels package for your GPU architecture, use the following command: .. code:: shell - apt-get install miopen-hip-kdb + apt-get install miopen-hip-kdb -Where ```` is the GPU architecture (e.g., ``gfx900``, ``gfx906``, ``gfx1030`` ). +Where ```` is the GPU architecture, for example, ``gfx900``, ``gfx906``, or ``gfx1030``. .. note:: - Not installing these packages doesn't impact the functioning of MIOpen, since MIOpen compiles - them on the target machine once you run the kernel. However, the compilation step may significantly - increase the startup time for different operations. + If you don't install these packages, it doesn't impact the functioning of MIOpen. This is because MIOpen compiles + them on the target machine after you run the kernel. However, the compilation step might significantly + increase the startup time for certain operations. The ``utils/install_precompiled_kernels.sh`` script provided as part of MIOpen automates the preceding process. It queries the user machine for the GPU architecture and then installs the appropriate -package. You can invoke it using: +package. To run it, use the following command: .. code:: shell - ./utils/install_precompiled_kernels.sh + ./utils/install_precompiled_kernels.sh The preceding script depends on the ``rocminfo`` package to query the GPU architecture. Installing dependencies --------------------------------------------------------------------------------------------------------- +============================================================== + +To install the MIOpen dependencies, use the ``install_deps.cmake`` command: -You can install dependencies using the ``install_deps.cmake`` script (``cmake -P install_deps.cmake``). +.. code:: shell + + cmake -P install_deps.cmake -By default, this installs to ``/usr/local``, but you can specify another location using the ``--prefix`` +By default, this installs the dependencies in ``/usr/local``, but you can specify another location using the ``--prefix`` argument: .. code:: shell cmake -P install_deps.cmake --prefix -An example CMake step is: +The following example demonstrates how to use ``cmake`` with a specific installation directory: .. code:: shell - cmake -P install_deps.cmake --minimum --prefix /root/MIOpen/install_dir + cmake -P install_deps.cmake --minimum --prefix /root/MIOpen/install_dir -You can use this prefix to specify the dependency path during the configuration phase using -``CMAKE_PREFIX_PATH``. +You can specify this directory during the configuration phase using ``CMAKE_PREFIX_PATH``. -MIOpen's HIP backend uses :doc:`rocBLAS ` by default. You can install rocBLAS' +MIOpen's HIP backend uses :doc:`rocBLAS ` by default. You can install the rocBLAS minimum release using ``apt-get install rocblas``. To disable rocBLAS, set the configuration flag ``-DMIOPEN_USE_ROCBLAS=Off``. rocBLAS is **not** available with OpenCL. -MIOpen's HIP backend can use :doc:`hipBLASLt `. You can install hipBLASLt's minimum -release using ``apt-get install hipblaslt``. In addition to needing hipblaslt, you will also need to -install :doc:`hipBLAS `. You can install hipBLAS's minimum release using ``apt-get install hipblas``. -To disable hipBLASLt, set the configuration flag ``-DMIOPEN_USE_HIPBLASLT=Off``. -hipBLASLt is **not** available with OpenCL. - -Building MIOpen from source -================================================ - -You can build MIOpen form source with a HIP backend or an OpenCL backend. - -HIP backend --------------------------------------------------------------------------------------------------------- - -First, create a build directory: - -.. code:: shell - - mkdir build; cd build; - -Next, configure CMake. You can set the backend using the ``-DMIOPEN_BACKEND`` CMake variable. - -Set the C++ compiler to ``clang++``. For the HIP backend (ROCm 3.5 and later), run: - -.. code:: shell - - export CXX= - cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH=";;" .. - -An example CMake step is: - -.. code:: shell - - export CXX=/opt/rocm/llvm/bin/clang++ && \ - cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" .. - -.. note:: - - When specifying the path for the `CMAKE_PREFIX_PATH` variable, **do not** use the tilde (`~`) - shorthand to represent the home directory. - -OpenCL backend --------------------------------------------------------------------------------------------------------- - -.. note:: - - OpenCL is deprecated. We recommend using a HIP backend and following the instructions listed in - the preceding section. - -First, run: - -.. code:: shell - - cmake -DMIOPEN_BACKEND=OpenCL .. - -The preceding code assumes OpenCL is installed in one of the standard locations. If not, then manually -set these CMake variables: - -.. code:: shell - - cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER= -DOPENCL_LIBRARIES= -DOPENCL_INCLUDE_DIRS= .. - -Here's an example dependency path for an environment in ROCm 3.5 and later: - -.. code:: shell - - cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER=/opt/rocm/llvm/bin/clang++ -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" .. - -.. _setting-up-locations: - -Setting up locations --------------------------------------------------------------------------------------------------------- - -By default, the install location is set to ``/opt/rocm``. You can change this using -``CMAKE_INSTALL_PREFIX``: - -.. code:: shell - - cmake -DMIOPEN_BACKEND=HIP -DCMAKE_INSTALL_PREFIX= .. - - -System performance database and user database --------------------------------------------------------------------------------------------------------- - -The default path to the system performance database (System PerfDb) is ``miopen/share/miopen/db/`` -within the install location. The default path to the user performance database (User PerfDb) is -``~/.config/miopen/``. For development purposes, setting `BUILD_DEV` changes the default path to -both database files to the source directory: - -.. code:: shell - - cmake -DMIOPEN_BACKEND=HIP -DBUILD_DEV=On .. - - -Database paths can be explicitly customized using the ``MIOPEN_SYSTEM_DB_PATH`` (System PerfDb) -and ``MIOPEN_USER_DB_PATH`` (User PerfDb) CMake variables. - -To learn more, refer to the -:doc:`performance database <../conceptual/perfdb>` documentation. - -Persistent program cache --------------------------------------------------------------------------------------------------------- - -By default, MIOpen caches device programs in the ``~/.cache/miopen/`` directory. Within the cache -directory, there is a directory for each version of MIOpen. You can change the location of the cache -directory during configuration using the ``-DMIOPEN_CACHE_DIR=`` flag. - -You can also disable the cache during runtime using the ``MIOPEN_DISABLE_CACHE=1`` environmental -variable. - -For MIOpen version 2.3 and earlier -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the compiler changes, or you modify the kernels, then you must delete the cache for the MIOpen -version in use (e.g., ``rm -rf ~/.cache/miopen/``). You can find more -information in the :doc:`cache <../conceptual/cache>` documentation. - -For MIOpen version 2.4 and later -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -MIOpen's kernel cache directory is versioned so that your cached kernels won't collide when upgrading -from an earlier version. - -Changing the CMake configuration --------------------------------------------------------------------------------------------------------- - -The configuration can be changed after running CMake (using ``ccmake``): - -``ccmake ..`` **or** ``cmake-gui``: ``cmake-gui ..`` - -The ``ccmake`` program can be downloaded as a Linux package (``cmake-curses-gui``), but is not -available on Windows. - -Building the library -========================================================= - -You can build the library from the ``build`` directory using the 'Release' configuration: - -``cmake --build . --config Release`` **or** ``make`` - -You can install it using the 'install' target: - -``cmake --build . --config Release --target install`` **or** ``make install`` - -This installs the library to the ``CMAKE_INSTALL_PREFIX`` path that you specified. - -Building the driver -========================================================= - -MIOpen provides an application driver that you can use to run any layer in isolation, and measure -library performance and verification. - -You can build the driver using the ``MIOpenDriver`` target: - -``cmake --build . --config Release --target MIOpenDriver`` **or** ``make MIOpenDriver`` - -Running the tests -========================================================= - -You can run tests using the 'check' target: - -``cmake --build . --config Release --target check`` **or** ``make check`` - -To build and run a single test, use the following code: - -.. code:: shell - - cmake --build . --config Release --target test_tensor - ./bin/test_tensor - -Formatting the code -========================================================= - -All the code is formatted using `clang-format`. To format a file, use: - -.. code:: shell - - clang-format-10 -style=file -i - -To format the code per commit, you can install githooks: - -.. code:: shell - - ./.githooks/install - -Storing large file using Git Large File Storage -========================================================= - -Git Large File Storage (LFS) replaces large files, such as audio samples, videos, datasets, and graphics -with text pointers inside Git, while storing the file contents on a remote server. In MIOpen, we use Gi -LFS to store our large files, such as our kernel database files (``*.kdb``) that are normally > 0.5 GB. - -You can install Git LFS using the following code: - -.. code:: shell - - sudo apt install git-lfs - git lfs install - -In the Git repository where you want to use Git LFS, track the file type using the following code (if the -file type has already been tracked, you can skip this step): - -.. code:: shell - - git lfs track "*.file_type" - git add .gitattributes - -You can pull all or a single large file using: - -.. code:: shell - - git lfs pull --exclude= - or - git lfs pull --exclude= --include "filename" - -Update the large files and push to GitHub using: - -.. code:: shell - - git add my_large_files - git commit -m "the message" - git push - -Installing the dependencies manually -=============================================================== - -If you're using Ubuntu v16, you can install the ``Boost`` packages using: - -.. code:: shell - - sudo apt-get install libboost-dev - sudo apt-get install libboost-system-dev - sudo apt-get install libboost-filesystem-dev - -.. note:: - - By default, MIOpen attempts to build with Boost statically linked libraries. If required, you can build - with dynamically linked Boost libraries using the `-DBoost_USE_STATIC_LIBS=Off` flag during the - configuration stage. However, this is not recommended. - -You must install the ``half`` header from the `half website `_. +MIOpen's HIP backend can use :doc:`hipBLASLt `. To install the minimum release of hipBLASLt, +use ``apt-get install hipblaslt``. In addition to installing hipBLASLt, you must also +install :doc:`hipBLAS `. To install the hipBLAS minimum release, use ``apt-get install hipblas``. +To disable hipBLASLt, set the configuration flag ``-DMIOPEN_USE_HIPBLASLT=Off``. +hipBLASLt is **not** available with OpenCL. \ No newline at end of file diff --git a/docs/install/prerequisites.rst b/docs/install/prerequisites.rst new file mode 100644 index 0000000000..14b43dc295 --- /dev/null +++ b/docs/install/prerequisites.rst @@ -0,0 +1,40 @@ +.. meta:: + :description: MIOpen prerequisites + :keywords: MIOpen, ROCm, API, documentation, prerequisites, install + +******************************************************************** +MIOpen prerequisites +******************************************************************** + +To install MIOpen, you must first install these prerequisites. These prerequisites apply to +all types of MIOpen installations. + +* A :doc:`ROCm `-enabled platform +* A base software stack that includes either: + + * :doc:`HIP ` (HIP and HCC libraries and header files) + * OpenCL (OpenCL libraries and header files), which is now deprecated + +* `ROCm CMake `_: CMake modules for common + build tasks needed for the ROCm software stack +* `Half `_: An IEEE 754-based, half-precision floating-point library +* `Boost `_: Version 1.79 is recommended, because older versions might need patches + to work on newer systems + + * MIOpen uses the ``boost-system`` and ``boost-filesystem`` packages to enable persistent + :doc:`kernel cache <../conceptual/cache>` + +* `SQLite3 `_: A read-write performance database +* lbzip2: A multi-threaded compression and decompression utility +* :doc:`rocBLAS `: AMD's library for Basic Linear Algebra Subprograms (BLAS) on the + ROCm platform. + + * Minimum version for pre-ROCm 3.5 + `master-rocm-2.10 `_ + * Minimum version for post-ROCm 3.5 + `master-rocm-3.5 `_ + +* `Multi-Level Intermediate Representation (MLIR) `_, with an + MIOpen dialect to support and complement kernel development +* :doc:`Composable Kernel `: A C++ templated device library for + GEMM-like and reduction-like operators. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 24a87f6dcb..8d248233da 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -3,30 +3,20 @@ defaults: maxdepth: 6 root: index subtrees: -- entries: - - file: what-is-miopen.rst - title: What is MIOpen? - caption: Install entries: + - file: install/prerequisites.rst + title: MIOpen prerequisites - file: install/install.rst title: Install MIOpen + - file: install/build-source.rst + title: Build MIOpen from source - file: install/docker-build.rst title: Build MIOpen using Docker - file: install/embed.rst title: Build MIOpen for embedded systems -- caption: Reference - entries: - - file: reference/index - title: API library - subtrees: - - entries: - - file: doxygen/html/modules - title: Modules - - file: reference/datatypes.rst - title: Datatypes - - caption: Conceptual entries: - file: conceptual/finddb.rst @@ -49,6 +39,18 @@ subtrees: - file: how-to/find-and-immediate.rst title: Use find APIs & immediate mode + +- caption: Reference + entries: + - file: reference/index + title: API library + subtrees: + - entries: + - file: doxygen/html/modules + title: Modules + - file: reference/datatypes.rst + title: Datatypes + - caption: About entries: - file: license.md diff --git a/docs/what-is-miopen.rst b/docs/what-is-miopen.rst deleted file mode 100644 index e77678b583..0000000000 --- a/docs/what-is-miopen.rst +++ /dev/null @@ -1,16 +0,0 @@ - -.. meta:: - :description: What is MIOpen? - :keywords: MIOpen, ROCm, API, documentation - -************************************************************* -What is MIOpen? -************************************************************* - -MIOpen is AMD's open-source, deep-learning primitives library for GPUs. It implements fusion to -optimize for memory bandwidth and GPU launch overheads, providing an auto-tuning infrastructure -to overcome the large design space of problem configurations. It also implements different algorithms -to optimize convolutions for different filter and input sizes. - -MIOpen is one of the first libraries to publicly support the bfloat16 datatype for convolutions, which -allows for efficient training at lower precision without loss of accuracy.