Skip to content

Commit 4a26726

Browse files
adeljo-amdadeljo-amd
committed
Docs: Add environment variable reference page
1 parent 84dcd25 commit 4a26726

File tree

3 files changed

+213
-6
lines changed

3 files changed

+213
-6
lines changed

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ The rocFFT public repository is located at `<https://github.com/ROCm/rocFFT>`_.
4747

4848
* :doc:`API usage <./reference/api>`
4949
* :doc:`API reference <./reference/allapi>`
50+
* :doc:`Environment variables <./reference/env-variables>`
5051

5152
To contribute to the documentation, see
5253
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.

‎docs/reference/env-variables.rst

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
.. meta::
2+
:description: rocFFT documentation and API reference library
3+
:keywords: rocFFT, ROCm, API, documentation, reference, environment variable, environment
4+
5+
********************************************************************
6+
rocFFT environment variables
7+
********************************************************************
8+
9+
This section describes the most important rocFFT environment variables,
10+
which are grouped by functionality.
11+
12+
Logging and debugging
13+
=====================
14+
15+
The logging and debugging environment variables for rocFFT are collected in the
16+
following table.
17+
18+
.. list-table::
19+
:header-rows: 1
20+
:widths: 70,30
21+
22+
* - **Environment variable**
23+
- **Value**
24+
25+
* - | ``ROCFFT_LAYER``
26+
| Controls which logging layers are active using bitmask values.
27+
- | ``0``: No logging
28+
| ``1``: Trace logging
29+
| ``2``: Bench logging
30+
| ``4``: Profile logging
31+
| ``8``: Plan logging
32+
| ``16``: Kernel I/O logging
33+
| ``32``: RTC logging
34+
| ``64``: Tuning logging
35+
| ``128``: Graph logging
36+
| Values can be combined with bitwise OR
37+
38+
* - | ``ROCFFT_LOG_TRACE_PATH``
39+
| Specifies file path for trace logging output.
40+
- | String path to trace log file
41+
| Used when trace logging is enabled via ``ROCFFT_LAYER``
42+
43+
* - | ``ROCFFT_LOG_BENCH_PATH``
44+
| Specifies file path for bench logging output.
45+
- | String path to bench log file
46+
| Used when bench logging is enabled via ``ROCFFT_LAYER``
47+
48+
* - | ``ROCFFT_LOG_PROFILE_PATH``
49+
| Specifies file path for profile logging output.
50+
- | String path to profile log file
51+
| Used when profile logging is enabled via ``ROCFFT_LAYER``
52+
53+
* - | ``ROCFFT_LOG_PLAN_PATH``
54+
| Specifies file path for plan logging output.
55+
- | String path to plan log file
56+
| Used when plan logging is enabled via ``ROCFFT_LAYER``
57+
58+
* - | ``ROCFFT_LOG_KERNELIO_PATH``
59+
| Specifies file path for kernel I/O logging output.
60+
- | String path to kernel I/O log file
61+
| Used when kernel I/O logging is enabled via ``ROCFFT_LAYER``
62+
63+
* - | ``ROCFFT_LOG_RTC_PATH``
64+
| Specifies file path for runtime compilation logging output.
65+
- | String path to RTC log file
66+
| Used when RTC logging is enabled via ``ROCFFT_LAYER``
67+
68+
* - | ``ROCFFT_LOG_TUNING_PATH``
69+
| Specifies file path for tuning logging output.
70+
- | String path to tuning log file
71+
| Used when tuning logging is enabled via ``ROCFFT_LAYER``
72+
73+
* - | ``ROCFFT_LOG_GRAPH_PATH``
74+
| Specifies file path for graph logging output.
75+
- | String path to graph log file
76+
| Used when graph logging is enabled via ``ROCFFT_LAYER``
77+
78+
Runtime compilation and caching
79+
===============================
80+
81+
The runtime compilation and caching environment variables for rocFFT are collected in
82+
the following table.
83+
84+
.. list-table::
85+
:header-rows: 1
86+
:widths: 70,30
87+
88+
* - **Environment variable**
89+
- **Value**
90+
91+
* - | ``ROCFFT_RTC_CACHE_PATH``
92+
| Sets the location for the read-write user-level cache of compiled kernels.
93+
- | String path to writable file location
94+
| Enables persistent caching across program runs
95+
96+
* - | ``ROCFFT_RTC_CACHE_READ_DISABLE``
97+
| Disables reading from the runtime compilation cache.
98+
- | ``0`` or unset: Enable cache reading
99+
| ``1``: Disable cache reading
100+
101+
* - | ``ROCFFT_RTC_CACHE_WRITE_DISABLE``
102+
| Disables writing to the runtime compilation cache.
103+
- | ``0`` or unset: Enable cache writing
104+
| ``1``: Disable cache writing
105+
106+
* - | ``ROCFFT_RTC_PROCESS_HELPER``
107+
| Specifies path to custom RTC helper process executable.
108+
- | String path to RTC helper executable
109+
| Used for out-of-process kernel compilation
110+
111+
Solution map and configuration
112+
==============================
113+
114+
The solution map and configuration environment variables for rocFFT are collected in the
115+
following table.
116+
117+
.. list-table::
118+
:header-rows: 1
119+
:widths: 70,30
120+
121+
* - **Environment variable**
122+
- **Value**
123+
124+
* - | ``ROCFFT_READ_EXPLICIT_SOL_MAP_FILE``
125+
| Specifies explicit solution map file to read.
126+
- | String path to solution map file
127+
| Overrides default solution map discovery
128+
129+
* - | ``ROCFFT_READ_SOL_MAP_FROM_FOLDER``
130+
| Specifies folder containing solution map files.
131+
- | String path to folder with solution map files
132+
| Loads architecture-specific and generic solution maps
133+
134+
Tuning and performance
135+
======================
136+
137+
The tuning and performance environment variables for rocFFT are collected in the
138+
following table.
139+
140+
.. list-table::
141+
:header-rows: 1
142+
:widths: 70,30
143+
144+
* - **Environment variable**
145+
- **Value**
146+
147+
* - | ``DUMP_TUNING``
148+
| Enables dumping of kernel tuning candidates to files.
149+
- | ``0`` or unset: Disable tuning dump
150+
| ``1``: Enable tuning dump
151+
152+
* - | ``TUNE_EXACT_PROB``
153+
| Controls exact problem tuning behavior.
154+
- | ``0`` or unset: Use default tuning behavior
155+
| ``1``: Enable exact problem tuning
156+
157+
* - | ``TUNING_WORKSPACE``
158+
| Specifies workspace directory for tuning operations.
159+
- | String path to tuning workspace directory
160+
| Used for storing tuning results and output files
161+
162+
* - | ``MIN_WGS``
163+
| Sets minimum workgroup size for kernel configuration tuning.
164+
- | Integer value specifying minimum workgroup size (default: 64)
165+
| Must be multiple of 64
166+
167+
* - | ``MAX_WGS``
168+
| Sets maximum workgroup size for kernel configuration tuning.
169+
- | Integer value specifying maximum workgroup size
170+
| Default varies by tuning phase (512 for phase 0, 768 for phase 1)
171+
172+
* - | ``ROCFFT_DEVICE_BW``
173+
| Specifies device memory bandwidth for performance calculations.
174+
- | Numeric value representing device bandwidth in GB/s
175+
| Overrides automatic detection from HIP device queries
176+
177+
* - | ``PRINT_REJECT_REASON``
178+
| Enables printing of kernel configuration rejection reasons.
179+
- | ``0`` or unset: Don't print rejection reasons
180+
| ``1``: Print rejection reasons
181+
182+
Development and debugging (advanced)
183+
====================================
184+
185+
The development and debugging environment variables for rocFFT are collected in the
186+
following table. These variables are primarily intended for debugging and development
187+
purposes.
188+
189+
.. list-table::
190+
:header-rows: 1
191+
:widths: 70,30
192+
193+
* - **Environment variable**
194+
- **Value**
195+
196+
* - | ``ROCFFT_DEBUG_GENERATE_KERNEL_HARNESS``
197+
| Enables generation of standalone kernel test harnesses.
198+
- | ``0`` or unset: Don't generate harness files
199+
| ``1``: Generate kernel harness files
200+
201+
* - | ``ROCFFT_DEBUG_KERNEL_HARNESS_PATH``
202+
| Specifies output directory for generated kernel harness files.
203+
- | String path for kernel harness output directory
204+
| Default: current working directory

‎docs/sphinx/_toc.yml.in

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,22 @@ subtrees:
66
- file: what-is-rocfft
77
title: What is rocFFT?
88

9-
- caption: Install
9+
- caption: Install
1010
entries:
1111
- file: install/building-installing-rocfft
12-
title: Installation guide
12+
title: Installation guide
1313

14-
- caption: Conceptual
14+
- caption: Conceptual
1515
entries:
1616
- file: conceptual/fft-computation
17-
title: FFT computation
17+
title: FFT computation
1818

1919
- caption: How to
2020
entries:
2121
- file: how-to/working-with-rocfft
2222
title: Work with rocFFT
2323
- file: how-to/real-data
24-
title: Use real data
24+
title: Use real data
2525
- file: how-to/load-store-callbacks
2626
title: Load and store callbacks
2727
- file: how-to/runtime-compilation
@@ -32,7 +32,7 @@ subtrees:
3232
- caption: Samples
3333
entries:
3434
- url: https://github.com/ROCm/rocFFT/tree/develop/clients/samples
35-
title: GitHub client examples
35+
title: GitHub client examples
3636

3737
- caption: API reference
3838
entries:
@@ -44,6 +44,8 @@ subtrees:
4444
title: API usage
4545
- file: reference/allapi
4646
title: API reference
47+
- file: reference/env-variables.rst
48+
title: Environment variables
4749

4850
- caption: About
4951
entries:

0 commit comments

Comments
 (0)