From 2c243feb1bd16a2f94ce597e8876d6737b4d5f00 Mon Sep 17 00:00:00 2001 From: Adel Johar Date: Mon, 1 Dec 2025 20:25:27 +0100 Subject: [PATCH] [Docs] Move environment variables to separate page (#341) [ROCm/rocshmem commit: ba77bdd9a6b5d41841623c9e567038cf2210e255] --- projects/rocshmem/docs/api/env_variables.rst | 58 ++++++++++++++++++++ projects/rocshmem/docs/compile_and_run.rst | 35 ------------ projects/rocshmem/docs/index.rst | 1 + projects/rocshmem/docs/sphinx/_toc.yml.in | 2 + 4 files changed, 61 insertions(+), 35 deletions(-) create mode 100644 projects/rocshmem/docs/api/env_variables.rst diff --git a/projects/rocshmem/docs/api/env_variables.rst b/projects/rocshmem/docs/api/env_variables.rst new file mode 100644 index 0000000000..b112589ea9 --- /dev/null +++ b/projects/rocshmem/docs/api/env_variables.rst @@ -0,0 +1,58 @@ +.. meta:: + :description: rocSHMEM environment variables reference + :keywords: rocSHMEM, ROCm, API, environment variables, environment, reference + +******************************************************************** +rocSHMEM environment variables +******************************************************************** + +This section describes the important environment variables used to +control the behavior of rocSHMEM. + +.. list-table:: + :header-rows: 1 + :widths: 35,14,51 + + * - **Environment variable** + - **Default value** + - **Value** + + * - | ``ROCSHMEM_HEAP_SIZE`` + | Defines the size of the rocSHMEM symmetric heap in bytes. + - ``1073741824`` (1 GB) + - | Size in bytes. + | Note the heap is on the GPU memory. + + * - | ``ROCSHMEM_MAX_NUM_CONTEXTS`` + | Defines the number of contexts an application can use. + - ``32`` + - Maximum number of contexts. + + * - | ``ROCSHMEM_MAX_NUM_TEAMS`` + | Defines the number of teams an application can use. + - ``40`` + - Maximum number of teams. + + * - | ``ROCSHMEM_UNIQUEID_WITH_MPI`` + | Defines whether rocSHMEM is expected to use MPI when using the uniqueId based initialization. + - ``0`` + - | 0: Do not use MPI. + | 1: Use MPI. + + * - | ``ROCSHMEM_DISABLE_MIXED_IPC`` + | Defines whether to force using the network conduit even when IPC is available. + - ``0`` + - | 0: Use IPC when available. + | 1: Force network conduit. + + * - | ``ROCSHMEM_GDA_ALTERNATE_QP_PORTS`` + | Enables/Disables having QPs alternate their mappings across rocSHMEM contexts. + - ``1`` + - | 0: Disabled. + | 1: Enabled (helps saturate bandwidth on multiport bonded interfaces). + + * - | ``ROCSHMEM_GDA_PCIE_RELAXED_ORDERING`` + | Enables PCIe Relaxed Ordering when registering the symmetric heap with the RDMA NICs. + - ``0`` + - | 0: Disabled. + | 1: Enabled. diff --git a/projects/rocshmem/docs/compile_and_run.rst b/projects/rocshmem/docs/compile_and_run.rst index 5e72899da6..c785a27e9d 100644 --- a/projects/rocshmem/docs/compile_and_run.rst +++ b/projects/rocshmem/docs/compile_and_run.rst @@ -58,38 +58,3 @@ See the `Open MPI documentation `_ for more have GPU support enabled. You must use the ``mpiexec`` from the expected MPI library, especially when using the MPI built by yourself as part of :ref:`install-dependencies`. - -Environment variables ---------------------- - -You can control the behavior of rocSHMEM by using the following environment variables: - -.. list-table:: Environment Variables - :widths: 30 10 20 - :header-rows: 1 - - * - Name - - Default Value - - Description - * - ROCSHMEM_HEAP_SIZE - - 1 - - Defines the size of the rocSHMEM symmetric heap in GB. - Note the heap is on the GPU memory. - * - ROCSHMEM_MAX_NUM_CONTEXTS - - 1024 - - Defines the number of contexts an application can use. - * - ROCSHMEM_MAX_NUM_TEAMS - - 40 - - Defines the number of teams an application can use. - * - ROCSHMEM_UNIQUEID_WITH_MPI - - 0 - - Defines whether rocSHMEM is expected to use MPI when using the uniqueId based initialization. - * - ROCSHMEM_DISABLE_MIXED_IPC - - 0 - - Defines whether to force using the network conduit even when IPC is available. - * - ROCSHMEM_GDA_ALTERNATE_QP_PORTS - - 1 - - Enables/Disables having QPs alternate their mappings across rocSHMEM contexts. This helps saturate bandwidth on multiport bonded interfaces. - * - ROCSHMEM_GDA_PCIE_RELAXED_ORDERING - - 0 - - Enables PCIe Relaxed Ordering when registering the symemtric heap with the RDMA NICs. diff --git a/projects/rocshmem/docs/index.rst b/projects/rocshmem/docs/index.rst index 4cd6f05d35..135884a9b9 100644 --- a/projects/rocshmem/docs/index.rst +++ b/projects/rocshmem/docs/index.rst @@ -27,6 +27,7 @@ The rocSHMEM public repository is located at ` * :doc:`Memory management routines <./api/memory_management>` * :doc:`Team management routines <./api/teams>` * :doc:`Context management routines <./api/ctx>` + * :doc:`Environment variables <./api/env_variables>` * :doc:`Remote memory access routines <./api/rma>` * :doc:`Atomic memory operations <./api/amo>` * :doc:`Signaling operations <./api/sigops>` diff --git a/projects/rocshmem/docs/sphinx/_toc.yml.in b/projects/rocshmem/docs/sphinx/_toc.yml.in index 23d28c607c..2ac92bc5e6 100644 --- a/projects/rocshmem/docs/sphinx/_toc.yml.in +++ b/projects/rocshmem/docs/sphinx/_toc.yml.in @@ -28,6 +28,8 @@ subtrees: title: Team management routines - file: api/ctx.rst title: Context management routines + - file: api/env_variables.rst + title: Environment Variables - file: api/rma.rst title: Remote memory access routines - file: api/amo.rst