From 49fd82dccbc7165fbbef11baa246f83e3f06bb07 Mon Sep 17 00:00:00 2001
From: Jeffrey Novotny <jnovotny@amd.com>
Date: Wed, 24 Jul 2024 09:17:22 -0400
Subject: [PATCH] Move troubleshooting to post-install of install.rst and other
 minor edits.

---
 docs/conceptual/how-omnitrace-works.rst     |  2 +-
 docs/how-to/configuring-runtime-options.rst |  2 +
 docs/how-to/using-omnitrace-api.rst         |  2 +-
 docs/install/install.rst                    | 61 ++++++++++++++++++++-
 4 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/docs/conceptual/how-omnitrace-works.rst b/docs/conceptual/how-omnitrace-works.rst
index 7bfb13520..4d2eaa0fc 100644
--- a/docs/conceptual/how-omnitrace-works.rst
+++ b/docs/conceptual/how-omnitrace-works.rst
@@ -6,7 +6,7 @@
 How Omnitrace works
 *******************
 
-This page explains the nomenclature necessary to use Omnitrace and provides 
+This topic explains the nomenclature necessary to use Omnitrace and provides 
 some basic tips to help you get started. It also explains the main data
 collection modes, including a comparison between binary instrumentation 
 and statistical sampling.
diff --git a/docs/how-to/configuring-runtime-options.rst b/docs/how-to/configuring-runtime-options.rst
index 8160cc729..16767087b 100644
--- a/docs/how-to/configuring-runtime-options.rst
+++ b/docs/how-to/configuring-runtime-options.rst
@@ -123,6 +123,8 @@ Here is a sample configuration for hardware counters:
    # using perf identifiers
    OMNITRACE_PAPI_EVENTS   = perf::INSTRUCTIONS perf::CACHE-REFERENCES perf::CACHE-MISSES
 
+.. _omnitrace_papi_events:
+
 OMNITRACE_PAPI_EVENTS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/how-to/using-omnitrace-api.rst b/docs/how-to/using-omnitrace-api.rst
index c6d30d539..f79154a49 100644
--- a/docs/how-to/using-omnitrace-api.rst
+++ b/docs/how-to/using-omnitrace-api.rst
@@ -6,7 +6,7 @@
 Using the Omnitrace API
 ****************************************************
 
-The following example shows how a program can use the Omnitrace API to analyze a program.
+The following example shows how a program can use the Omnitrace API for run-time analysis.
 
 Omnitrace user API example program
 ========================================
diff --git a/docs/install/install.rst b/docs/install/install.rst
index 84027cdba..10f0ff89a 100644
--- a/docs/install/install.rst
+++ b/docs/install/install.rst
@@ -336,4 +336,63 @@ issues locating the installed libraries:
 .. note::
 
    If ROCm support is enabled, you might have to add the path to the ROCm libraries to ``LD_LIBRARY_PATH``,
-   for example, ``export LD_LIBRARY_PATH=/opt/rocm/lib:${LD_LIBRARY_PATH}``.
\ No newline at end of file
+   for example, ``export LD_LIBRARY_PATH=/opt/rocm/lib:${LD_LIBRARY_PATH}``.
+
+Post-installation troubleshooting
+========================================
+
+This section explains how to resolve certain issues that might happen when you first use Omnitrace.
+
+Issues with RHEL and SELinux
+----------------------------------------------------
+
+RHEL (Red Hat Enterprise Linux) distributions of Linux automatically enable a security feature 
+named SELinux (Security-Enhanced Linux) that prevents Omnitrace from running.
+This issue applies to systems running the CentOS 9 operating system using
+any version of the AMD ROCm Software alongside an AMD Instinct MI300 GPU.
+
+The problem occurs after you instrument a program and try to
+run ``omnitrace-run`` with the instrumented program.
+
+.. code-block:: shell
+
+   g++ hello.cpp -o hello
+   omniperf-instrument -M sampling -o hello.instr -- ./hello
+   omnitrace-run -- ./hello.instr
+
+Instead of successfully running the binary with call-stack sampling, 
+Omnitrace crashes with a segmentation fault.
+
+To workaround this problem, either disable SELinux or configure it to use a more 
+permissive setting.
+
+To avoid this problem for the duration of the current session, run this command 
+from the shell:
+
+.. code-block:: shell
+
+   sudo setenforce 0
+
+For a permanent workaround, edit the SELinux configuration file using the command
+``sudo vim /etc/sysconfig/selinux`` and change the ``SELINUX`` setting to 
+either ``Permissive`` or ``Disabled``.
+
+.. note::
+
+   Permanently changing the SELinux settings can have security implications. 
+   Ensure you review your system security settings before making any changes.
+
+Modifying RPATH details
+----------------------------------------------------
+
+If you're experiencing problems loading your application with an instrumented library, 
+then you might have to check and modify the RPATH specified in your application. 
+See the section on `troubleshooting RPATHs <../how-to/instrumenting-rewriting-binary-application.html#rpath-troubleshooting>`_
+for further details.
+
+Configuring PAPI to collect hardware counters
+----------------------------------------------------
+
+To use PAPI to collect the majority of hardware counters, ensure 
+the ``/proc/sys/kernel/perf_event_paranoid`` setting has a value less than or equal to ``2``. 
+For more information, see the :ref:`omnitrace_papi_events` section.
\ No newline at end of file