clean up installation guides

Signed-off-by: Peter Jun Park <[email protected]>

docs/index.rst

@@ -11,19 +11,19 @@ In addition to a full deployment guide with installation instructions, this
 documentation also explains the ideas motivating the design behind the tool and
 its components.
 
+See Omniperf source code at `<https://github.com/ROCm/omniperf>`__.
+
 If you're new to Omniperf, acquaint yourself with the tool by reviewing the
 chapters that follow and gradually learn its more advanced features. To get
 started, see :doc:`What is Omniperf? <what-is-omniperf>`.
 
-See Omniperf source code at `<https://github.com/ROCm/omniperf>`__.
-
 .. grid:: 2
    :gutter: 3
 
    .. grid-item-card:: Install
 
-      * :doc:`install/quick-start`
-      * :doc:`install/omniperf`
+      * :doc:`install/core-install`
+      * :doc:`install/grafana-setup`
 
    .. grid-item::
 
@@ -34,11 +34,6 @@ in practice.
 .. grid:: 2
    :gutter: 3
 
-   .. grid-item-card:: Conceptual
-
-      * :doc:`conceptual/overview`
-      * :doc:`conceptual/performance-model`
-
    .. grid-item-card:: How to
 
       * :doc:`how-to/profiling`
@@ -48,6 +43,11 @@ in practice.
 
       * `Omniperf example exercises <https://github.com/amd/HPCTrainingExamples/tree/main/OmniperfExamples>`_
 
+   .. grid-item-card:: Conceptual
+
+      * :doc:`conceptual/overview`
+      * :doc:`conceptual/performance-model`
+
    .. grid-item-card:: Reference
 
       * :doc:`reference/compatible-accelerators`

docs/install/core-install.rst

@@ -0,0 +1,191 @@
+.. meta::
+   :description: Omniperf installation and deployment
+   :keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, AMD,
+              install, deploy, Grafana, client, configuration, modulefiles
+
+*********************************
+Installing and deploying Omniperf
+*********************************
+
+Omniperf consists of two installation components.
+
+* :ref:`Omniperf core installation <core-install>`
+
+  * Provides the core application profiling capability.
+  * Allows the collection of performance counters, filtering by hardware
+    block, dispatch, kernel, and more.
+  * Provides a CLI-based analysis mode.
+  * Provides a standalone web interface for importing analysis metrics.
+
+* :doc:`Grafana server for Omniperf <grafana-setup>` (optional)
+
+  * Hosts the MongoDB backend and Grafana instance.
+  * Is packaged in a Docker container for easy setup.
+
+Determine what you need to install based on how you would like to interact with
+Omniperf. See the following decision tree to help determine what installation is
+right for you.
+
+.. image:: ../data/install/install-decision-tree.png
+   :align: center
+   :alt: Decision tree for installing and deploying Omniperf
+
+.. _core-install:
+
+Core installation
+=================
+
+The core Omniperf application requires the following basic software
+dependencies.
+
+* Python ``>= 3.8``
+* CMake ``>= 3.19``
+* ROCm ``>= 5.7.1``
+
+Omniperf depends on a number of Python packages documented in the top-level
+``requirements.txt`` file. Install these *before* configuring Omniperf.
+
+.. admonition:: Optional packages for developers
+
+   For those looking to build Omniperf as a developer, consider these additional
+   requirements.
+
+   .. list-table::
+       :header-rows: 1
+
+       * - Requirements file
+         - Description
+
+       * - ``docs/sphinx/requirements.txt``
+         - Python packages required to build this documentation from source.
+
+       * - ``requirements-test.txt``
+         - Python packages required to run Omniperf's CI suite using PyTest.
+
+   The recommended procedure for Omniperf usage is to install into a shared file
+   system so that multiple users can access the final installation. The
+   following steps illustrate how to install the necessary Python dependencies
+   using `pip <https://packaging.python.org/en/latest/>`_ and Omniperf into a
+   shared location controlled by the ``INSTALL_DIR`` environment variable.
+
+.. _core-install-cmake-vars:
+
+Configuration variables
+-----------------------
+The following installation example leverages several
+`CMake <https://cmake.org/cmake/help/latest>`_ project variables defined as
+follows.
+
+.. list-table::
+    :header-rows: 1
+
+    * - CMake variable
+      - Description
+
+    * - ``CMAKE_INSTALL_PREFIX``
+      - Controls the install path for Omniperf files.
+
+    * - ``PYTHON_DEPS``
+      - Specifies an optional path to resolve Python package dependencies.
+
+    * - ``MOD_INSTALL_PATH``
+      - Specifies an optional path for separate Omniperf modulefile installation.
+
+.. _core-install-steps:
+
+Installation steps
+------------------
+
+#. A typical install begins by downloading the latest release tarball available
+   from `<https://github.com/ROCm/omniperf/releases>`__. From there, untar and
+   navigate into the top-level directory.
+
+   .. code-block:: shell
+
+      tar xfz omniperf-v{__VERSION__}.tar.gz
+      cd omniperf-v{__VERSION__}
+
+#. Next, install Python dependencies and complete the Omniperf configuration and
+   install process.
+
+   .. code-block:: shell
+
+      # define top-level install path
+      export INSTALL_DIR=<your-top-level-desired-install-path>
+
+      # install python deps
+      python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
+
+      # configure Omniperf for shared install
+      mkdir build
+      cd build
+      cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{__VERSION__} \
+              -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
+              -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles ..
+
+      # install
+      make install
+
+   .. tip::
+
+      You might need to ``sudo`` the final installation step if you don't have
+      write access for the chosen installation path.
+
+#. Upon successful installation, your top-level installation directory should
+   look like this.
+
+   .. code-block:: shell
+
+      $ ls $INSTALL_DIR
+      modulefiles  {__VERSION__}  python-libs
+
+.. _core-install-modulefiles:
+
+Execution using modulefiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The installation process includes the creation of an environment modulefile for
+use with `Lmod <https://lmod.readthedocs.io>`_. On systems that support Lmod,
+you can register the Omniperf modulefile directory and setup your environment
+for execution of Omniperf as follows.
+
+.. code-block:: shell
+
+   $ module use $INSTALL_DIR/modulefiles
+   $ module load omniperf
+   $ which omniperf
+   /opt/apps/omniperf/{__VERSION__}/bin/omniperf
+
+   $ omniperf --version
+   ROC Profiler:   /opt/rocm-5.1.0/bin/rocprof
+
+   omniperf (v{__VERSION__})
+
+.. tip::
+
+   If you're relying on an Lmod Python module locally, you may wish to customize
+   the resulting Omniperf modulefile post-installation to include extra
+   module dependencies.
+
+Execution without modulefiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use Omniperf without the companion modulefile, update your ``PATH``
+settings to enable access to the command line binary. If you installed Python
+dependencies in a shared location, also update your `PYTHONPATH` configuration.
+
+.. code-block:: shell
+
+   export PATH=$INSTALL_DIR/{__VERSION__}/bin:$PATH
+   export PYTHONPATH=$INSTALL_DIR/python-libs
+
+.. _core-install-rocprof-var:
+
+ROCProfiler
+-----------
+
+Omniperf relies on ROCProfiler's ``rocprof`` binary during the profiling
+process. Normally, the path to this binary is detected automatically, but you
+can override the path by the setting the optional `ROCPROF` environment
+variable.
+