Docs: Add Environment Variable Page (#395)

Co-authored-by: Adel Johar <adel.johar@amd.com>

.gitignore

@@ -1,6 +1,7 @@
 .venv
 .vscode
 build
+__pycache__
 
 # documentation artifacts
 _build/

docs/conceptual/gpu-isolation.md

@@ -34,7 +34,7 @@ Runtime
 
 ```{code-block} shell
 :caption: Example to expose the 1. device and a device based on UUID.
-export ROCR_VISIBLE_DEVICES="0,GPU-DEADBEEFDEADBEEF"
+export ROCR_VISIBLE_DEVICES="0,GPU-4b2c1a9f-8d3e-6f7a-b5c9-2e4d8a1f6c3b"
 ```
 
 ### `GPU_DEVICE_ORDINAL`

docs/conf.py

@@ -8,6 +8,7 @@ import os
 import shutil
 import sys
 from pathlib import Path
+from subprocess import run
 
 gh_release_path = os.path.join("..", "RELEASE.md")
 gh_changelog_path = os.path.join("..", "CHANGELOG.md")
@@ -84,6 +85,9 @@ html_context = {"docs_header_version": "7.1.1"}
 if os.environ.get("READTHEDOCS", "") == "True":
     html_context["READTHEDOCS"] = True
 
+# Check if the branch is a docs/ branch
+official_branch = run(["git", "rev-parse", "--abbrev-ref", "HEAD"], capture_output=True, text=True).stdout.find("docs/")
+
 # configurations for PDF output by Read the Docs
 project = "ROCm Documentation"
 project_path = os.path.abspath(".").replace("\\", "/")
@@ -202,7 +206,7 @@ external_toc_path = "./sphinx/_toc.yml"
 # Add the _extensions directory to Python's search path
 sys.path.append(str(Path(__file__).parent / 'extension'))
 
-extensions = ["rocm_docs", "sphinx_reredirects", "sphinx_sitemap", "sphinxcontrib.datatemplates", "version-ref", "csv-to-list-table"]
+extensions = ["rocm_docs", "sphinx_reredirects", "sphinx_sitemap", "sphinxcontrib.datatemplates", "remote-content", "version-ref", "csv-to-list-table"]
 
 compatibility_matrix_file = str(Path(__file__).parent / 'compatibility/compatibility-matrix-historical-6.0.csv')
 
@@ -216,6 +220,10 @@ html_context = {"docs_header_version": "7.1.0"}
 if os.environ.get("READTHEDOCS", "") == "True":
     html_context["READTHEDOCS"] = True
 
+html_context["official_branch"] = official_branch
+html_context["version"] = version
+html_context["release"] = release
+
 html_theme = "rocm_docs_theme"
 html_theme_options = {"flavor": "rocm-docs-home"}
 

docs/extension/remote-content.py

@@ -0,0 +1,141 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import ViewList
+from sphinx.util import logging
+from sphinx.util.nodes import nested_parse_with_titles
+import requests
+import re
+
+logger = logging.getLogger(__name__)
+
+class BranchAwareRemoteContent(Directive):
+    """
+    Directive that downloads and includes content from other repositories,
+    matching the branch/tag of the current documentation build.
+
+    Usage:
+    .. remote-content::
+       :repo: owner/repository
+       :path: path/to/file.rst
+       :default_branch: docs/develop  # Branch to use when not on a release
+       :tag_prefix: Docs/  # Optional
+    """
+
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = False
+    option_spec = {
+        'repo': str,
+        'path': str,
+        'default_branch': str,  # Branch to use when not on a release tag
+        'start_line': int,      # Include the file from a specific line
+        'tag_prefix': str,      # Prefix for release tags (e.g., 'Docs/')
+    }
+
+    def get_current_version(self):
+        """Get current version/branch being built"""
+        env = self.state.document.settings.env
+        html_context = env.config.html_context
+
+        # Check if building from a tag
+        if "official_branch" in html_context:
+            if html_context["official_branch"] == 0:
+                if "version" in html_context:
+                    # Remove any 'v' prefix
+                    version = html_context["version"]
+                    if re.match(r'^\d+\.\d+\.\d+$', version):
+                        return version
+
+        # Not a version tag, so we'll use the default branch
+        return None
+
+    def get_target_ref(self):
+        """Get target reference for the remote repository"""
+        current_version = self.get_current_version()
+
+        # If it's a version number, use tag prefix and version
+        if current_version:
+            tag_prefix = self.options.get('tag_prefix', '')
+            return f'{tag_prefix}{current_version}'
+
+        # For any other case, use the specified default branch
+        if 'default_branch' not in self.options:
+            logger.warning('No default_branch specified and not building from a version tag')
+            return None
+
+        return self.options['default_branch']
+
+    def construct_raw_url(self, repo, path, ref):
+        """Construct the raw.githubusercontent.com URL"""
+        return f'https://raw.githubusercontent.com/{repo}/{ref}/{path}'
+
+    def fetch_and_parse_content(self, url, source_path):
+        """Fetch content and parse it as RST"""
+        response = requests.get(url)
+        response.raise_for_status()
+        content = response.text
+
+        start_line = self.options.get('start_line', 0)
+
+        # Create ViewList for parsing
+        line_count = 0
+        content_list = ViewList()
+        for line_no, line in enumerate(content.splitlines()):
+            if line_count >= start_line:
+                content_list.append(line, source_path, line_no)
+            line_count+=1 
+
+        # Create a section node and parse content
+        node = nodes.section()
+        nested_parse_with_titles(self.state, content_list, node)
+
+        return node.children
+
+    def run(self):
+        if 'repo' not in self.options or 'path' not in self.options:
+            logger.warning('Both repo and path options are required')
+            return []
+
+        target_ref = self.get_target_ref()
+        if not target_ref:
+            return []
+
+        raw_url = self.construct_raw_url(
+            self.options['repo'],
+            self.options['path'],
+            target_ref
+        )
+
+        try:
+            logger.info(f'Attempting to fetch content from {raw_url}')
+            return self.fetch_and_parse_content(raw_url, self.options['path'])
+        except requests.exceptions.RequestException as e:
+            logger.warning(f'Failed to fetch content from {raw_url}: {str(e)}')
+
+            # If we failed on a tag, try falling back to default_branch
+            if re.match(r'^\d+\.\d+\.\d+$', target_ref) or target_ref.startswith('Docs/'):
+                if 'default_branch' in self.options:
+                    try:
+                        fallback_ref = self.options['default_branch']
+                        logger.info(f'Attempting fallback to {fallback_ref}...')
+
+                        fallback_url = self.construct_raw_url(
+                            self.options['repo'],
+                            self.options['path'],
+                            fallback_ref
+                        )
+
+                        return self.fetch_and_parse_content(fallback_url, self.options['path'])
+                    except requests.exceptions.RequestException as e2:
+                        logger.warning(f'Fallback also failed: {str(e2)}')
+
+            return []
+
+def setup(app):
+    app.add_directive('remote-content', BranchAwareRemoteContent)
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/index.md

@@ -65,6 +65,8 @@ ROCm documentation is organized into the following categories:
 * [ROCm libraries](./reference/api-libraries.md)
 * [ROCm tools, compilers, and runtimes](./reference/rocm-tools.md)
 * [GPU hardware specifications](./reference/gpu-arch-specs.rst)
+* [Hardware atomics operation support](./reference/gpu-atomics-operation.rst)
+* [Environment variables](./reference/env-variables.rst)
 * [Data types and precision support](./reference/precision-support.rst)
 * [Graph safe support](./reference/graph-safe-support.rst)
 <!-- markdownlint-enable MD051 -->

docs/reference/env-variables.rst

@@ -0,0 +1,173 @@
+.. meta::
+    :description: Environment variables reference
+    :keywords: AMD, ROCm, environment variables, environment, reference, settings
+
+.. role:: cpp(code)
+   :language: cpp
+
+.. _env-variables-reference:
+
+*************************************************************
+ROCm environment variables
+*************************************************************
+
+ROCm provides a set of environment variables that allow users to configure and optimize their development
+and runtime experience. These variables define key settings such as installation paths, platform selection,
+and runtime behavior for applications running on AMD accelerators and GPUs.
+
+This page outlines commonly used environment variables across different components of the ROCm software stack,
+including HIP and ROCR-Runtime. Understanding these variables can help streamline software development and
+execution in ROCm-based environments.
+
+HIP environment variables
+=========================
+
+The following tables list the HIP environment variables.
+
+GPU isolation variables
+--------------------------------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/rocm-systems
+   :path: /projects/hip/docs/reference/env_variables/gpu_isolation_hip_env.rst
+   :default_branch: develop
+   :tag_prefix: docs/
+
+
+Profiling variables
+--------------------------------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/rocm-systems
+   :path: /projects/hip/docs/reference/env_variables/profiling_hip_env.rst
+   :default_branch: develop
+   :tag_prefix: docs/
+
+
+Debug variables
+--------------------------------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/rocm-systems
+   :path: /projects/hip/docs/reference/env_variables/debug_hip_env.rst
+   :default_branch: develop
+   :tag_prefix: docs/
+
+Memory management related variables
+--------------------------------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/rocm-systems
+   :path: /projects/hip/docs/reference/env_variables/memory_management_hip_env.rst
+   :default_branch: develop
+   :tag_prefix: docs/
+
+Other useful variables
+--------------------------------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/rocm-systems
+   :path: /projects/hip/docs/reference/env_variables/miscellaneous_hip_env.rst
+   :default_branch: develop
+   :tag_prefix: docs/
+
+ROCR-Runtime environment variables
+==================================
+
+The following table lists the ROCR-Runtime environment variables:
+
+.. remote-content::
+   :repo: ROCm/ROCR-Runtime
+   :path: runtime/docs/data/env_variables.rst
+   :default_branch: amd-staging
+   :tag_prefix: docs/
+
+HIPCC environment variables
+===========================
+
+This topic provides descriptions of the HIPCC environment variables.
+
+.. remote-content::
+   :repo: ROCm/llvm-project
+   :path: amd/hipcc/docs/env.rst
+   :default_branch: amd-staging
+   :start_line: 14
+   :tag_prefix: docs/
+
+Environment variables in ROCm libraries
+=======================================
+
+Many ROCm libraries define environment variables for specific tuning, debugging,
+or behavioral control. The table below provides an overview and links to further
+documentation.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30, 70
+
+    * - Library
+      - Purpose of Environment Variables
+
+    * - :doc:`hipBLASLt <hipblaslt:reference/env-variables>`
+      - Manage logging, debugging, offline tuning, and stream-K configuration
+        for hipBLASLt.
+
+    * - :doc:`hipSPARSELt <hipsparselt:reference/env-variables>`
+      - Control logging, debugging and performance monitoring of hipSPARSELt.
+
+    * - :doc:`rocBLAS <rocblas:reference/env-variables>`
+      - Performance tuning, kernel selection, logging, and debugging for BLAS
+        operations.
+
+    * - :doc:`rocSolver <rocsolver:reference/env_variables>`
+      - Control logging of rocSolver.
+
+    * - :doc:`rocSPARSE <rocsparse:reference/env_variables>`
+      - Control logging of rocSPARSE.
+
+    * - :doc:`MIGraphX <amdmigraphx:reference/MIGraphX-dev-env-vars>`
+      - Control debugging, testing, and model performance tuning options for
+        MIGraphX.
+
+    * - :doc:`MIOpen <miopen:reference/env_variables>`
+      - Control MIOpen logging and debugging, find mode and algorithm behavior
+        and others.
+
+    * - :doc:`MIVisionX <mivisionx:reference/MIVisionX-env-variables>`
+      - Control core OpenVX, GPU/device and debugging/profiling, stitching and
+        chroma key configurations, file I/O operations, model deployment, and
+        neural network parameters of MIVisionX.
+
+    * - :doc:`RCCL <rccl:api-reference/env-variables>`
+      - Control the logging, debugging, compiler and assembly behavior, and
+        cache of RPP.
+
+    * - :doc:`RPP <rpp:reference/rpp-env-variables>`
+      - Logging, debugging, compiler and assembly management, and cache control in RPP
+
+    * - `Tensile <https://rocm.docs.amd.com/projects/Tensile/en/latest/src/reference/environment-variables.html>`_
+      - Enable testing, debugging, and experimental features for Tensile clients and applications
+
+Key single-variable details
+===========================
+
+This section provides detailed descriptions, in the standard format, for ROCm
+libraries that feature a single, key environment variable (or a very minimal set)
+which is documented directly on this page for convenience.
+
+.. _rocalution-vars-detail:
+
+rocALUTION
+----------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 70,30
+
+    * - Environment variable
+      - Value
+
+    * - | ``ROCALUTION_LAYER``
+        | If set to ``1``, enable file logging. Logs each rocALUTION function call including object constructor/destructor, address of the object, memory allocation, data transfers, all function calls for matrices, vectors, solvers, and preconditioners. The log file is placed in the working directory.
+      - | ``1`` (Enable trace file logging)
+        | Default: Not set.

docs/sphinx/_toc.yml.in

@@ -216,6 +216,8 @@ subtrees:
     title: ROCm tools, compilers, and runtimes
   - file: reference/gpu-arch-specs.rst
   - file: reference/gpu-atomics-operation.rst
+  - file: reference/env-variables.rst
+    title: Environment variables
   - file: reference/precision-support.rst
     title: Data types and precision support
   - file: reference/graph-safe-support.rst