From 45ddca5967df44c5e8f900ac577c13f58bf8d6af Mon Sep 17 00:00:00 2001 From: spolifroni-amd Date: Tue, 1 Oct 2024 11:02:57 -0400 Subject: [PATCH] fix merge conflict --- README.md | 11 ++-- docs/dev/contributing-to-migraphx.rst | 36 +++++------ docs/dev/dev_intro.rst | 1 + docs/index.rst | 33 ++++++---- docs/install/build_and_install_with_cmake.rst | 62 +++++++++++++++++++ .../install/build_and_install_with_docker.rst | 52 ++++++++++++++++ .../install/build_and_install_with_rbuild.rst | 32 ++++++++++ docs/install/building_migraphx.rst | 32 ++++++++++ docs/install/installing_with_package.rst | 21 +++++++ docs/sphinx/_toc.yml.in | 9 ++- docs/what-is-migraphx.rst | 13 ---- 11 files changed, 246 insertions(+), 56 deletions(-) create mode 100644 docs/install/build_and_install_with_cmake.rst create mode 100644 docs/install/build_and_install_with_docker.rst create mode 100644 docs/install/build_and_install_with_rbuild.rst create mode 100644 docs/install/building_migraphx.rst create mode 100644 docs/install/installing_with_package.rst delete mode 100644 docs/what-is-migraphx.rst diff --git a/README.md b/README.md index e9de3f5624b..63f9c4d9856 100755 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # AMD MIGraphX AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference. -To use MIGraphX, you can install the binaries or build from source code. Refer to the following sections -for Ubuntu installation instructions (we'll provide instructions for other Linux distributions in the future). -> [!NOTE] -> You must [install ROCm](https://rocm.docs.amd.com/en/latest/deploy/linux/quick_start.html) before +>[!NOTE] +>The published documentation is available at [MIGraphX](https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/) in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the `docs` folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html). + +> [!NOTE] +> You must [install ROCm](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/index.html) before > installing MIGraphX. ## Installing from binaries @@ -16,7 +17,7 @@ Install binaries using: sudo apt update && sudo apt install -y migraphx ``` -Header files and libraries are installed under `/opt/rocm-`, where `` is the ROCm +Header files and libraries are installed under ``/opt/rocm-``, where ```` is the ROCm version. ## Building from source diff --git a/docs/dev/contributing-to-migraphx.rst b/docs/dev/contributing-to-migraphx.rst index 36ec533c076..4405c0489ac 100644 --- a/docs/dev/contributing-to-migraphx.rst +++ b/docs/dev/contributing-to-migraphx.rst @@ -5,24 +5,22 @@ .. _contributing-to-migraphx: ========================== -Contributing to MIGraphX +Developing for MIGraphX ========================== -This document explains the internal implementation of some commonly used MIGraphX APIs. You can utilize the information provided in this document and other documents under "Contributing to MIGraphX" section to contribute to the MIGraphX API implementation. -Here is how some basic operations in the MIGraphX framework are performed. +This document is intended for anyone who wants to contribute to MIGraphX. This document covers some basic operations that can be used to develop for MIGraphX. The complete source code for the example shown here can be found at `ref_dev_examples.cpp `_ on the MIGraphX repository. -Performing basic operations +More examples can be found on `the MIGraphX GitHub repository `_. + + +Adding two literals ---------------------------- A program is a collection of modules, which are collections of instructions to be executed when calling :cpp:any:`eval `. Each instruction has an associated :cpp:any:`operation ` which represents the computation to be performed by the instruction. -The following code snippets demonstrate some basic operations using MIGraphX. - -Adding literals -****************** +We start with a snippet of the simple ``add_two_literals()`` function:: -Here is a ``add_two_literals()`` function:: // create the program and get a pointer to the main module migraphx::program p; @@ -55,7 +53,7 @@ To compile the program for the GPU, move the file to ``test/gpu/`` directory and #include Adding Parameters -******************* +---------------------------- While the ``add_two_literals()`` function above demonstrates add operation on constant values ``1`` and ``2``, the following program demonstrates how to pass a parameter (``x``) to a module using ``add_parameter()`` function . @@ -86,7 +84,7 @@ To map the parameter ``x`` to an :cpp:any:`argument () == 6); Handling Tensor Data -********************** +---------------------------- The above two examples demonstrate scalar operations. To describe multi-dimensional tensors, use the :cpp:any:`shape ` class to compute a simple convolution as shown below:: @@ -132,7 +130,7 @@ By default, the buffers are allocated on the CPU when compiling for CPU and on t To locate the buffers on the CPU even when compiling for GPU, set the option ``offload_copy=true``. Importing From ONNX -********************** +---------------------------- To make it convenient to use neural networks directly from other frameworks, MIGraphX ONNX parser allows you to build a :cpp:any:`program ` directly from an ONNX file. For usage, refer to the ``parse_onnx()`` function below:: @@ -140,22 +138,16 @@ For usage, refer to the ``parse_onnx()`` function below:: program p = migraphx::parse_onnx("model.onnx"); p.compile(migraphx::gpu::target{}); -Sample programs ------------------ - -You can find all the MIGraphX examples in the `Examples `_ directory. -Build MIGraphX source code -**************************** +Build this example +---------------------------- -To build a sample program `ref_dev_examples.cpp `_, use: +Build the `ref_dev_examples.cpp `_ example with this command: make -j$(nproc) test_ref_dev_examples -This creates an executable file ``test_ref_dev_examples`` in the ``bin/`` of the build directory. +This creates the ``test_ref_dev_examples`` under ``bin/`` in the build directory. To verify the build, use: make -j$(nproc) check - -For detailed instructions on building MIGraphX from source, refer to the `README `_ file. diff --git a/docs/dev/dev_intro.rst b/docs/dev/dev_intro.rst index ac8c05cc26d..f22f1d36f17 100644 --- a/docs/dev/dev_intro.rst +++ b/docs/dev/dev_intro.rst @@ -2,6 +2,7 @@ Developer Introduction ====================== MIGraphX provides an optimized execution engine for deep learning neural networks. + We will cover some simple operations in the MIGraphX framework here. For a quick start guide to using MIGraphX, look in the examples directory: ``https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx``. diff --git a/docs/index.rst b/docs/index.rst index 2e4c39be183..8ec6956816a 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,34 +5,41 @@ .. _index: =========================== -AMD MIGraphX documentation +MIGraphX documentation =========================== -Welcome to the MIGraphX docs home page! To learn more, see :ref:`what-is-migraphx`. +MIGraphX is a graph inference engine and graph compiler. MIGraphX accelerates machine-learning models by leveraging several graph-level transformations and optimizations. These optimizations include: -Our documentation is structured as follows: +* Operator fusion +* Arithmetic simplifications +* Dead-code elimination +* Common subexpression elimination (CSE) +* Constant propagation + +After optimization, MIGraphX generates code for AMD GPUs by calling various ROCm libraries to create the fastest combinations of HIP kernels. + +The MIGraphX public repository is located at `https://github.com/ROCm/AMDMIGraphX/ `_ .. grid:: 2 :gutter: 3 - .. grid-item-card:: Reference + .. grid-item-card:: Install + + * :doc:`Installing MIGraphX <./install/installing_with_package>` + + .. grid-item-card:: Using the MIGraphX API * :ref:`cpp-api-reference` * :ref:`python-api-reference` * :ref:`migraphx-driver` - .. grid-item-card:: Contribution + .. grid-item-card:: Contributing to the MIGraphX code base - * :ref:`contributing-to-migraphx` + * :doc:`Building MIGraphX <./install/building_migraphx>` + * :doc:`Developing for MIGraphX <./dev/contributing-to-migraphx>` To contribute to the documentation refer to -`Contributing to ROCm `_. +`Contribute to ROCm documentation `_. Licensing information can be found on the `Licensing `_ page. - -Index and search -================== - -* :ref:`genindex` -* :ref:`search` diff --git a/docs/install/build_and_install_with_cmake.rst b/docs/install/build_and_install_with_cmake.rst new file mode 100644 index 00000000000..0c34f31f642 --- /dev/null +++ b/docs/install/build_and_install_with_cmake.rst @@ -0,0 +1,62 @@ +.. meta:: + :description: Build and install MIGraphX using CMake + :keywords: build, install, MIGraphX, AMD, ROCm, CMake + +******************************************************************** +Build and install MIGraphX using CMake +******************************************************************** + +ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux `_ for information on how to install ROCm on Linux. + +.. note:: + + This method for building MIGraphX requires using ``sudo``. + + +1. Install the dependencies: + + .. code:: shell + + sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*') + + .. note:: + + If ``rbuild`` is not installed on your system, install it with: + + .. code:: shell + + pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz + +2. Create a build directory and change directory to it: + + .. code:: shell + + mkdir build + cd build + +3. Configure CMake: + + .. code:: shell + + CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*') + +4. Build MIGraphX source code: + + .. code:: shell + + make -j$(nproc) + + + You can verify this using: + + .. code:: shell + + make -j$(nproc) check + + +5. Install MIGraphX libraries: + + .. code:: shell + + make install + \ No newline at end of file diff --git a/docs/install/build_and_install_with_docker.rst b/docs/install/build_and_install_with_docker.rst new file mode 100644 index 00000000000..95057d3dfe0 --- /dev/null +++ b/docs/install/build_and_install_with_docker.rst @@ -0,0 +1,52 @@ +.. meta:: + :description: Installing MIGraphX using Docker + :keywords: install, MIGraphX, AMD, ROCm, Docker + +******************************************************************** +Installing MIGraphX using Docker +******************************************************************** + +ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux `_ for information on how to install ROCm on Linux. + +.. note:: + + Docker commands are run using ``sudo``. + +1. Build the Docker image. This command will install all the prerequisites required to install MIGraphX. Ensure that you are running this in the same directory as ``Dockerfile``. + + .. code:: shell + + sudo docker build -t migraphx . + + +2. Create and run the container. Once this command is run, you will be in the ``/code/AMDMIGraphX`` directory of a pseudo-tty. + + .. code:: shell + + sudo docker run --device='/dev/kfd' --device='/dev/dri' -v=`pwd`:/code/AMDMIGraphX -w /code/AMDMIGraphX --group-add video -it migraphx + +3. In the ``/code/AMDMIGraphX``, create a ``build`` directory, then change directory to ``/code/AMDMIGraphX/build``: + + .. code:: shell + + mkdir build + cd build + + +4. Configure CMake: + + .. code:: shell + + CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*') + +4. Build the MIGraphX libraries: + + .. code:: shell + + make -j$(nproc) + +5. Install the libraries: + + .. code:: shell + + make install \ No newline at end of file diff --git a/docs/install/build_and_install_with_rbuild.rst b/docs/install/build_and_install_with_rbuild.rst new file mode 100644 index 00000000000..3e962244940 --- /dev/null +++ b/docs/install/build_and_install_with_rbuild.rst @@ -0,0 +1,32 @@ +.. meta:: + :description: Build and install MIGraphX using rbuild + :keywords: build, install, MIGraphX, AMD, ROCm, rbuild + +******************************************************************** +Build and install MIGraphX using rbuild +******************************************************************** + +ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux `_ for information on how to install ROCm on Linux. + +.. note:: + + This method for building MIGraphX requires using ``sudo``. + +1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`: + + .. code:: shell + + sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip + +2. Install `rbuild `_: + + .. code:: shell + + pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz + + +3. Build MIGraphX source code: + + .. code:: shell + + sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*') diff --git a/docs/install/building_migraphx.rst b/docs/install/building_migraphx.rst new file mode 100644 index 00000000000..91656791583 --- /dev/null +++ b/docs/install/building_migraphx.rst @@ -0,0 +1,32 @@ +.. meta:: + :description: Build and install MIGraphX + :keywords: build, install, MIGraphX, AMD, ROCm, rbuild, development, contributing + +******************************************************************** +Building MIGraphX +******************************************************************** + +ROCm must be installed prior to building MIGraphX. See `ROCm installation for Linux `_ for information on ROCm installation on Linux. + +.. note:: + + This method for building MIGraphX requires using ``sudo``. + +1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`: + + .. code:: shell + + sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip + +2. Install `rbuild `_: + + .. code:: shell + + pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz + + +3. Build MIGraphX source code: + + .. code:: shell + + sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*') diff --git a/docs/install/installing_with_package.rst b/docs/install/installing_with_package.rst new file mode 100644 index 00000000000..0e9b67ff2a9 --- /dev/null +++ b/docs/install/installing_with_package.rst @@ -0,0 +1,21 @@ +.. meta:: + :description: Installing MIGraphX using the package installer + :keywords: install, MIGraphX, AMD, ROCm, package installer + +******************************************************************** +Installing MIGraphX +******************************************************************** + +ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux `_ for information on how to install ROCm on Linux. + +Installing MIGraphX using the package installer is sufficient for users who want to use the MIGraphX API. + +If you want to develop for MIGraphX and contribute to the source code, see `Building MIGraphX `_ and `Developing for MIGraphX `_ + +The package installer will install all the prerequisites needed for MIGraphX. + +Use the following command to install MIGraphX: + + .. code:: shell + + sudo apt update && sudo apt install -y migraphx \ No newline at end of file diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 63003d96ce5..88b1383424f 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -2,8 +2,10 @@ # These comments will also be removed. root: index subtrees: - - entries: - - file: what-is-migraphx + + - caption: Installation + entries: + - file: install/installing_with_package - caption: Reference entries: @@ -14,8 +16,9 @@ subtrees: - entries: - file: reference/driver-options - - caption: Contribution + - caption: Developing for MIGraphX entries: + - file: install/building_migraphx - file: dev/contributing-to-migraphx subtrees: - entries: diff --git a/docs/what-is-migraphx.rst b/docs/what-is-migraphx.rst deleted file mode 100644 index 20ea4800696..00000000000 --- a/docs/what-is-migraphx.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. meta:: - :description: MIGraphX provides an optimized execution engine for deep learning neural networks - :keywords: MIGraphX, ROCm, library, API - -.. _what-is-migraphx: - -===================== -What is MIGraphX? -===================== - -AMD MIGraphX is AMD's graph inference engine that accelerates machine learning model inference. The optimized execution engine is useful for deep learning neural networks. - -You can utilize MIGraphX functions using :ref:`C++ APIs `, :ref:`Python APIs `, and the :ref:`command-line tool migraphx-driver `.