From 81b7745f8e42482362c18fc7d02771cb412f054a Mon Sep 17 00:00:00 2001 From: Istvan Kiss Date: Wed, 19 Nov 2025 17:40:26 +0100 Subject: [PATCH] Docs: Add Environment Variable Page (#395) Co-authored-by: Adel Johar --- .gitignore | 1 + docs/conceptual/gpu-isolation.md | 2 +- docs/conf.py | 10 +- docs/extension/remote-content.py | 141 +++++++++++++++++++++++++ docs/index.md | 2 + docs/reference/env-variables.rst | 173 +++++++++++++++++++++++++++++++ docs/sphinx/_toc.yml.in | 2 + 7 files changed, 329 insertions(+), 2 deletions(-) create mode 100644 docs/extension/remote-content.py create mode 100644 docs/reference/env-variables.rst diff --git a/.gitignore b/.gitignore index 63583c6c3..5c0dcbe85 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .venv .vscode build +__pycache__ # documentation artifacts _build/ diff --git a/docs/conceptual/gpu-isolation.md b/docs/conceptual/gpu-isolation.md index 35a221779..7296df968 100644 --- a/docs/conceptual/gpu-isolation.md +++ b/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` diff --git a/docs/conf.py b/docs/conf.py index 10b7892cf..50bd2d19b 100644 --- a/docs/conf.py +++ b/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"} diff --git a/docs/extension/remote-content.py b/docs/extension/remote-content.py new file mode 100644 index 000000000..aad07c9b4 --- /dev/null +++ b/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, + } diff --git a/docs/index.md b/docs/index.md index be6026ef3..397ef5134 100644 --- a/docs/index.md +++ b/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) diff --git a/docs/reference/env-variables.rst b/docs/reference/env-variables.rst new file mode 100644 index 000000000..dc1073bb4 --- /dev/null +++ b/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 ` + - Manage logging, debugging, offline tuning, and stream-K configuration + for hipBLASLt. + + * - :doc:`hipSPARSELt ` + - Control logging, debugging and performance monitoring of hipSPARSELt. + + * - :doc:`rocBLAS ` + - Performance tuning, kernel selection, logging, and debugging for BLAS + operations. + + * - :doc:`rocSolver ` + - Control logging of rocSolver. + + * - :doc:`rocSPARSE ` + - Control logging of rocSPARSE. + + * - :doc:`MIGraphX ` + - Control debugging, testing, and model performance tuning options for + MIGraphX. + + * - :doc:`MIOpen ` + - Control MIOpen logging and debugging, find mode and algorithm behavior + and others. + + * - :doc:`MIVisionX ` + - 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 ` + - Control the logging, debugging, compiler and assembly behavior, and + cache of RPP. + + * - :doc:`RPP ` + - Logging, debugging, compiler and assembly management, and cache control in RPP + + * - `Tensile `_ + - 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. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 28d4dc37b..d0f66d9b7 100644 --- a/docs/sphinx/_toc.yml.in +++ b/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