Update hip variables

.gitignore

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

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 = {}
 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 = {}
 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

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

docs/reference/env-variables.rst

@@ -0,0 +1,183 @@
+.. 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/HIP
+   :path: docs/reference/env_variables/gpu_isolation_hip_env.rst
+   :default_branch: docs/develop
+   :tag_prefix: docs/
+
+
+Profiling variables
+------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/HIP
+   :path: docs/reference/env_variables/profiling_hip_env.rst
+   :default_branch: docs/develop
+   :tag_prefix: docs/
+
+
+
+Debug variables
+------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/HIP
+   :path: docs/reference/env_variables/debug_hip_env.rst
+   :default_branch: docs/develop
+   :tag_prefix: docs/
+
+
+
+Memory management related variables
+------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/HIP
+   :path: docs/reference/env_variables/memory_management_hip_env.rst
+   :default_branch: docs/develop
+   :tag_prefix: docs/
+
+
+
+Other useful variables
+------------------------------------------------------
+
+.. remote-content::
+   :repo: ROCm/HIP
+   :path: docs/reference/env_variables/miscellaneous_hip_env.rst
+   :default_branch: docs/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
+===========================
+
+.. remote-content::
+   :repo: ROCm/llvm-project
+   :path: amd/hipcc/docs/env.rst
+   :default_branch: amd-staging
+   :start_line: 10
+   :tag_prefix: docs/
+
+Additional component environment variables
+==========================================
+
+Many ROCm libraries and tools 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
+
+    * - Component
+      - Purpose of Environment Variables
+
+    * - `rocBLAS <https://rocm.docs.amd.com/projects/rocBLAS/en/latest/docs/ENV_VARIABLES.html>`_
+      - Performance tuning, kernel selection, logging, and debugging for BLAS operations.
+
+    * - `rocSPARSE <https://rocm.docs.amd.com/projects/rocSPARSE/en/latest/docs/ENV_VARIABLES.html>`_
+      - Algorithm control, debugging, and enabling/disabling specific features for sparse linear algebra.
+
+    * - `MIOpen <https://rocm.docs.amd.com/projects/MIOpen/en/latest/docs/ENV_VARIABLES.html>`_
+      - Extensive options for deep learning kernel tuning, find/enforce modes, solver selection, and verbose debugging.
+
+    * - `AMD SMI <#amd-smi-vars-detail>`_
+      - Control CLI output format (e.g., forcing JSON).
+
+    * - `rocFFT <#rocfft-vars-detail>`_
+      - Manage plan caching behavior and enable debugging for FFT operations.
+
+    * - `rocRAND <https://rocm.docs.amd.com/projects/rocRAND/en/latest/docs/USER_GUIDE.html#environment-variables>`_
+      - Control seeding behavior, select specific generators (if applicable), and assist in debugging random number generation.
+
+    * - rocDecode
+      - N/A
+
+    * - `rocTracer <https://rocm.docs.amd.com/projects/rocTracer/en/latest/docs/ENV_VAR.html>`_
+      - Configure API call interception, data collection parameters, and output for tracing and profiling.
+
+    * - `rocProfiler <https://rocm.docs.amd.com/projects/rocProfiler/en/latest/docs/ENVIRONMENT_VARIABLES.html>`_
+      - Control profiling activities, data collection, output formats, and tool behavior.
+
+Key single-variable details
+===========================
+
+This section provides detailed descriptions, in the standard format, for ROCm components
+that feature a single, key environment variable (or a very minimal set) which is documented
+directly on this page for convenience.
+
+.. _amd-smi-vars-detail:
+
+AMD SMI
+-------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 70,30
+
+    * - Environment variable
+      - Value
+
+    * - | ``ROCM_SMI_JSON_OUTPUT``
+        | If set to ``1``, forces the ``rocm-smi`` command-line tool to produce output in JSON format,
+        | overriding any command-line flags for output format. Useful for scripting.
+      - | ``1`` (Enable JSON output)
+        | Default: Not set (Output format determined by CLI flags or defaults to text).
+
+.. _rocfft-vars-detail:
+
+rocFFT
+------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 70,30
+
+    * - Environment variable
+      - Value
+
+    * - | ``ROCFFT_CACHE_PATH``
+        | Specifies the directory path where rocFFT should store and look for pre-compiled kernel
+        | caches (plans). Using a persistent cache can significantly reduce plan creation time
+        | for repeated FFT configurations.
+      - | *Path to a directory*
+        | Default: Not set (Caching might occur in a temporary or default system location, or be disabled).

docs/sphinx/_toc.yml.in

@@ -214,6 +214,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